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ABOUT THIS PUBLICATION 



VS APL is a program product that interprets and executes statements written 
in APL (A Programming Language). This publication describes how to install 
VS APL and how to perform various system management functions such as 
converting workspaces, defining VS APL users, and maintaining public and 
project libraries. It is intended for those who have responsibility for these 
functions. The reader is assumed to have knowledge of VS APL and 
Conversational Monitor System (CMS), which runs under VM/370, or VS 
Personal Computing (VSPC), which runs under OS/VS1 (Program Number 
5740-XR5), OS/VS2 MVS (Program Number 5740-XR6), or DOS/VS 

I (Program Number 5746-XR3). (For the remainder of the publication, the 
term OS/VS2 will be used to represent OS/VS2 MVS.) 

Major Divisions of the Publication 

"Introduction" describes the components of VS APL. 

"VS APL Distribution Volume" describes the contents and format of the VS 
APL distribution volume. 

"Installing VS APL under VM/370 (CMS)" explains how to install VS APL 
as a shared or non-shared system under VM/370 (CMS). 

"Installing VS APL under OS/VS (VSPC)" explains how to install VS APL 
as a foreground processor under OS/VS (VSPC). 

"Installing VS APL under DOS/VS (VSPC)" explains how to install VS APL 
as a foreground processor under DOS/VS (VSPC). 

"Defining VS APL Users" explains how to define VS APL users to the host 
system. 

"Defining Auxiliary Processors" explains how to define auxiliary processors 
to the host system. 

"VS APL Public and Project Libraries" explains how to create and maintain 
VS APL public and project libraries. 

"Workspace Conversion" explains how to convert APL\360, APLSV, and 
APL/CMS workspaces to VS APL workspaces for use under CMS or VSPC. 

"Transporting Workspaces between CMS and VSPC" explains how to 
transport VS APL workspaces between CMS and VSPC. 

"Using the VS APL Microcode Assist" discusses the use of the VS APL 
microcode assist feature. 

"Storage Requirements" presents virtual storage and auxiliary storage 
requirements for VS APL. 

"Messages" contains information about error and diagnostic messages. 

"Appendix A. VS APL Components" lists the items contained in each 
component of VS APL. 

"Appendix B. Sample Terminal Session for VS APL under CMS" contains a 
sample terminal session that can be used to test that VS APL is installed 
correctly under CMS. 
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"Appendix C. Sample Terminal Session for VS APL under VSPC" contains a 
sample terminal session that can be used to test that VS APL is installed 
correctly under OS/VS (VSPC) or DOS/VS (VSPC). 



Conventions Used in the Publication 



Required Publications 



The conventions used in describing the syntax of commands and statements 
are: 

• Expressions enclosed in brackets, [], are optional. 

• Items separated by an OR sign, | , are alternatives, only one of which may 
be specified. 

• Uppercase items must be entered as shown except that they may be 
truncated if so noted and, if entered at a terminal, they may be entered as 
either lowercase or uppercase. 

• Lowercase items are variables for which a value is substituted. 

• Parentheses, (), must be entered as shown. 



All readers must be familiar with some of the information presented in this 
publication: 

• VS APL General Information, GH20-9064, which provides a general 
description of VS APL. 

Readers concerned with VS APL under CMS must be familiar with some of 
the information presented in these publications: 

. IBM Virtual Machine Facility/ 3 70: Introduction, GC20-1 800, which 
provides a general description of VM/370 and CMS. 

• IBM Virtual Machine Facility/ 3 70: Command Language Guide for 
General Users, GC20- 1804, which provides basic information about CMS 
and CP for VM/370 Release 2. 

. IBM Virtual Machine Facility/ 3 70: Operator's Guide, GC20-1806, 
which describes how to define VM/370 users and CMS virtual disks. 

. IBM Virtual Machine Facility/ 3 70: EDIT Guide, GC20- 1805, which 
describes how to use the CMS editor for VM/370 Release 2. 

. VS APL for CMS: Terminal User's Guide, SH20-9067, which 
describes how to use VS APL under CMS. 

. IBM Virtual Machine Facility/ 3 70: CMS User's Guide, GC20-1819, 
which provides basic information about CMS and how to use the CMS 
editor to create and modify programs for VM/370 Release 3. 

• IBM Virtual Machine Facility/ 3 70: CP Command Reference for 
General Users, GC20-1820, which provides basic information about CP 
for VM/370 Release 3. 

• IBM Virtual Machine Facility/ 3 70: Command and Macro Reference, 
GC20-1818, which provides reference material on CMS commands, 
subcommands, and macros for VM/370 Release 3. 
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Related Publications 



Readers concerned with VS APL under VSPC must be familiar with some of 
the information presented in these publications: 

• VS Personal Computing (VSPC) for OS/VS and DOS/VS: General 
Information, GH20-9070, which provides a general description of VSPC. 

• VS Personal Computing (VSPC) Installation Reference Material, 
SH20-9072, which describes the VSPC Service Program and VSPC 
commands. This publication also contains information on OS/VS and 
DOS/VS (VSPC) messages. 

•. VS APL for VSPC: Terminal User's Guide, SH20-9066, which 
describes how to use VS APL under VSPC. 

Readers concerned with VS APL under OS/VS (VSPC) must be familiar 
with some of the information presented in this publication: 

• OS/VS JCL Reference, GC28-06 18, which describes the OS/VS JCL 
statements used in this publication. 

Readers concerned with VS APL under DOS/VS (VSPC) must be familiar 
with some of the information presented in this publication: 

• DOS/VS System Control Statements, GC33-5376, which describes the 
DOS/VS control statements used in this publication. 



Readers may need to be familiar with some of the information presented in 
these publications: 

• Operator's Library: System/ 3 70 Model 135 Procedures, GC38-0005, 
which explains how to load the VS APL microcode assist feature on a 
System/370, Model 135. 

• IBM System/ 370 Model 145 Operating Procedures, GC38-0015, which 
explains how to load the VS APL microcode assist feature on a 
System/370, Model 145. 

. IBM Virtual Machine Facility/ 370: System Messages, GC20-1808, 
which lists CP and CMS messages. 

• DOS/VS Messages, GC33-5379, which lists DOS/VS (VSPC) messages. 

• IBM Virtual Machine Facility/ 370: System Programmer's Guide, 
GC20-1807, which describes shared systems. 

• IBM Virtual Machine Facility/ 370: Planning and System Generation 
Guide, GC20-1801, which describes how to implement a shared system. 
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SUMMARY OF AMENDMENTS 

Release 2, October, 1976 

New Auxiliary Processors and Distributed Workspaces 

New Programming Features 

VS APL is distributed with the following additional items: 

Item Description 

Full Screen Management An auxiliary processor (number 1 24) that can 
auxiliary processor be used with VS APL under VSPC. 

CMS VSAM An auxiliary processor (number 123) that can 

auxiliary processor be used with VS APL under CMS. 

MEDIT A public library 1 workspace. 

SEDIT A public library 1 workspace. 

HOWEDITS A public library 1 workspace. 

SBIC A public library 1 workspace. 

VSAPLFILE A public library 2 workspace (VS APL under 

VSPC). 

FULLSCREEN A public library 2 workspace (VS APL under 

VSPC). 

PRINT A public library 2 workspace (VS APL under 

CMS). 

Information pertinent to these new items has been added to the Introduction, 
to the sample terminal session for VS APL under CMS, and to the 
descriptions of the VS APL distribution volume, VS APL installation 
procedures for CMS and VSPC, and auxiliary processors. 

DOS/VS Conversion Program 

New Programming Feature 

VS APL now includes a workspace conversion program (APLCVDOS) that 
executes under DOS/VS (VSPC). A description of the procedure for 
executing the DOS/VS conversion program is now provided in the chapter 
"Workspace Conversion." 

DOS/VS Installation Information 

Service Changes 

A new chapter, describing how to install VS APL under DOS/VS (VSPC), 
has been added to the text. Virtual and auxiliary storage requirements for VS 
APL under DOS/VS (VSPC) have been added to the chapter "Storage 
Requirements." 
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Transporting Workspaces 

Service Change 



Various changes have been made to the procedures shown for VS APL 
workspace transport from CMS to VSPC and from VSPC to CMS. 
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INTRODUCTION 



VS APL is a program product that interprets and executes statements written 
in APL (A Programming Language). It runs under: 

• Conversational Monitor System (CMS), which runs under VM/370 

• VS Personal Computing (VSPC), which runs under OS/VS1, OS/VS2, 
and DOS/VS 

VS APL is divided into the six components described below. 

Interpreter: Scans, analyzes, and executes VS APL statements. It is fully 
independent of the environment in which VS APL operates. It is free of all 
dependencies on terminal type, library organization, host system, and other 
characteristics of a particular installation. 

Executor: Provides environment-dependent services for the interpreter, such 
as access to libraries and terminal input and output. There are two versions of 
the executor, one for use under CMS and one for use under VSPC. 

Shared Storage Manager: Enables programs that are operating concurrently 
to communicate with each other via shared variables. The shared storage 
manager distributed with VS APL is used only under CMS. Under VSPC, the 
shared storage manager is a component of VSPC. 

Auxiliary Processors: Provide services to VS APL users via shared variables. 
There are four internal auxiliary processors for use under VSPC; they are 
distributed as part of the executor. There are five auxiliary processors for use 
under CMS; they are distributed as a separate component. Also distributed 
with VS APL, for use under CMS only, is a set of macros that can be used to 
write auxiliary processors. Distributed with VSPC is a set of similar macros 
that comprise the VSPC background interface. 

Conversion Program: Converts APL \ 3 60, APLSV, and APL/CMS 
workspaces to VS APL workspaces. There are four versions of the conversion 
program, two for use under CMS, one for use under OS/VS, and one for use 
under DOS/VS. 

Distributed Workspaces: Provide useful functions for VS APL users. They are 
described in VS APL for CMS: Terminal User's Guide and VS APL for 
VSPC: Terminal User's Guide. 
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VS APL DISTRIBUTION VOLUME 



The VS APL distribution volume contains all the components of VS APL and 
the sample job control statements and procedures used to install it. For 
installation under VM/370 (CMS) and OS/VS (VSPC), the distribution 
volume is an unlabeled tape. For installation under DOS/VS (VSPC), the 
distribution volume is either an unlabeled tape or a disk. The format of the 
distribution tape volume is shown in Figure 1 . The format of the distribution 
disk volume is shown in Figure 2. 
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File 

Number Contents 



File Characteristics 
RECFM LRECL BLKSIZE 



9 
10 
11 
12 
13 
14 
15 
16 
17 
18 
19 
20 
21 
22 
23 
24 



All object code for DOS/VS (VSPC); 
interpreter, executor (including internal 
auxiliary processors), and conversion 
program. 

Sample job control statements to install 
under DOS/VS and to run the conversion 
program. 

Sample job control statements to install 
under OS/VS and to run the conversion 
program. 

EXEC procedure to install under CMS; 
in CMS TAPE DUMP format. 

Object code for the interpreter for CMS 
and OS/VS (VSPC). 

Object code and other data for CMS; 
executor, shared storage manager, 
auxiliary processors and auxiliary 
processor macros, conversion programs, 
and conversion procedures; in CMS TAPE 
DUMP format. 

Object code for OS/VS (VSPC); executor 
(including internal auxiliary processors), 
and conversion program. 

Workspace 1 NEWS 

Workspace 1 WSFNS 

Workspace 1 CONVERT 

Workspace 1 TYPEDRILL 

Workspace 1 APLCOURSE 

Workspace 1 PLOT 

Workspace 1 EXAMPLES 

Workspace 1 FORMAT 

Workspace 1 MEDIT 

Workspace 1 SEDIT 

Workspace 1 HOWEDITS 

Workspace 1 SBIC 

Workspace 2 VSFILES 1 

Workspace 2 VSAPLFILEi 

Workspace 2 FULLS CREENl 

Workspace 2 APFNS 2 

Workspace 2 PRINT 2 



FB 



* Workspace is used only under VSPC. 

2 Workspace is used only under CMS. 

Figure 1 . Format of VS APL Distribution Tape Volume 



FB 



80 



80 



80 



3440 



80 



80 



805 805 



FB 80 3200 



805 805 



80 



3200 



F 


800 


800 


F 


800 


800 


F 


800 


800 


F 


800 


800 


F 


800 


800 


F 


800 


800 


F 


800 


800 


F 


800 


800 


F 


800 


800 


F 


800 


800 


F 


800 


800 


F 


800 


800 


F 


800 


800 


F 


800 


800 


F 


800 


800 


F 


800 


800 


F 


800 


800 
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Data Set Name 
A5748AP1.DOSVSOBJ.VSAPL 



A5748AP1.DOSVSJCL.VSAPL 

A5748AP1.NEWS.VSAPL 
A5748AP1 .WSFNS. VSAPL 
A5748AP1.CONVERT. VSAPL 
A5748AP1 .TYPEDRIL.VSAPL 
A5748AP1.APLCOURS. VSAPL 
A5748AP1. PLOT. VSAPL 
A5748AP1 .EXAMPLES.VSAPL 
A5748AP1 .FORMAT. VSAPL 
A5748AP1.MEDIT. VSAPL 
A5748AP1 .SEDIT.VSAPL 
A5748AP1 .HOWEDITS. VSAPL 
A5748AP1.SBIC.VSAPL 
A5748AP1.VSFILES.VSAPL 
A5748AP1 .VSAPLFIL. VSAPL 
A5748AP1.FULLSCRE.VSAPL 



Contents 

All object code for DOS/VS (VSPC); 
interpreter, executor (including 
internal auxiliary processors), 
and conversion program. 

Sample job control statements to 
install under DOS/VS and to run 
the conversion program. 



File Characteristics 
RECFM LRECL 



FB 



80 



80 



BLKSIZE 

3440 



80 



Workspace 1 NEWS 


FB 


80 


800 


Workspace 1 WSFNS 


FB 


80 


800 


Workspace 1 CONVERT 


FB 


80 


800 


Workspace 1 TYPEDRILL 


FB 


80 


800 


Workspace 1 APLCOURSE 


FB 


80 


800 


Workspace 1 PLOT 


FB 


80 


800 


Workspace 1 EXAMPLES 


FB 


80 


800 


Workspace 1 FORMAT 


FB 


80 


800 


Workspace 1 MEDIT 


FB 


80 


800 


Workspace 1 SEDIT 


FB 


80 


800 


Workspace 1 HOWEDITS 


FB 


80 


800 


Workspace 1 SBIC 


FB 


80 


800 


Workspace 2 VSFILES 


FB 


80 


800 


Workspace 2 VSAPLFILE 


FB 


80 


800 


Workspace 2 FULLSCREEN 


FB 


80 


800 



Figure 2. Format of VS APL Distribution Disk Volume 
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INSTALLING VS APL UNDER VM/370 (CMS) 

This section describes how to install VS APL as a shared or non-shared 
system under VM/370 (CMS). Installing VS APL as a shared system makes 
more efficient use of real storage and improves system performance. When 
VS APL is a shared system, all users share one copy of the VS APL executor, 
interpreter, and shared storage manager; an initialization routine and translate 
tables (executor modules APLSCINI and APLSCTBL) reside in each user's 
virtual machine. When VS APL is a non-shared system, the VS APL 
executor, interpreter, and shared storage manager reside in each user's virtual 
machine. Whether VS APL is shared or not, any auxiliary processors invoked 
by a user reside in his virtual machine. 

Before installing VS APL as a shared system, you should be familiar with the 
information about saved systems and shared segments presented in IBM 
Virtual Machine Facility/ 370: System Programmer's Guide and IBM 
Virtual Machine Facility/ 370: Planning and System Generation Guide. 

Requirements for Installation 

The facilities required for installing VS APL under VM/370 (CMS) are: 

• A System/370 machine configuration that can support VM/370 (CMS). 

• An installed release of VM/370 (CMS) of the required level or later: 
Release 3 (Program Level Change 1 ) if installing VS APL as a shared 
system; Release 2 (Program Level Change 13) if installing VS APL as a 
non-shared system. PTF number V03314 must be applied to CMS if it is 
not included in the release. 

• A virtual machine large enough to install VS APL (see "Virtual Storage 
Requirements"). 

• A magnetic tape device. 

• The VS APL distribution tape. 

• A CMS A-disk large enough to contain the VS APL distributed files (see 
"Auxiliary Storage Requirements"). 

• A CMS Y-disk large enough to contain the generated VS APL system (see 
"Auxiliary Storage Requirements"). 

• If installing VS APL as a shared system, space on a CP-owned DASD 
volume for the system (see "Auxiliary Storage Requirements"). 

• A terminal supported by CMS. 
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Overview of Installation Procedure 



Installation Procedure 



In brief, the procedure for installing VS APL under VM/370 (CMS) is as 
follows. The procedure is described in detail in the next section. 

1 . Plan and define the CMS disks required for VS APL. 

2. If installing VS APL as a shared system, plan the system's load address and 
DASD space allocation. 

3. Log on to VM/370 and IPL CMS. 

4. Access and prepare the A-disk and the Y-disk. 

5. Access the distribution tape. 

6. Transfer file APLINSTL EXEC (the CMS procedure that builds VS APL) 
from the distribution tape to the A-disk. 

7. Build VS APL by executing procedure APLINSTL. 

8. If installing VS APL as a shared system, define, load, and save the system. 

9. Test that VS APL is installed correctly by executing the sample terminal 
session (see Appendix B). 



1 . Plan the disk arrangement for the VS APL system, and define the disks as 
described in IBM Virtual Machine Facility/ 3 70: Operator's Guide. Two 
disks are required: 

• One which is accessed as the A-disk during execution of the installation 
procedure. It will contain all the files transferred from the distribution 
tape and the module files created in step 7. The minimum space required 
is shown in "Auxiliary Storage Requirements." Additional space should 
be allocated for future maintenance. At completion of the procedure, 
the A-disk should be kept as backup. 

• One which is accessed as the Y-disk during execution of the installation 
procedure. It will contain the generated VS APL system. The minimum 
space required is shown in "Auxiliary Storage Requirements." 
Additional space should be allocated for public workspaces other than 
those distributed. The Y-disk will be accessed by VS APL users. It 
should be defined with a write password known only to those who are 
responsible for installing and maintaining VS APL. 

2. If installing VS APL as a shared system, decide what the load address of 
the shared system will be. The address must be larger than the largest 
virtual machine of any VS APL user; the shared system must not overlay 
any other saved segment that will be attached at the same time as VS APL. 
The load address should not be unnecessarily high; if it is, real storage is 
wasted for unreferenced CP segment table entries. During step 7 of the 
installation procedure, enter the load address when prompted to do so. 

Also allocate permanent space on a CP-owned DASD volume to contain 
the saved system. For the space required, see "Auxiliary Storage 
Requirements." 

3. Log on to VM/370 and IPL CMS with a virtual machine large enough to 
install VS APL (see "Virtual Storage Requirements"). 
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4. Access the A-disk and the Y-disk in read/write mode. If the disks are 
newly allocated, format them using the CMS FORMAT command. 

If the disks are not newly allocated, issue the CMS LISTFILE command, 
and check that no files with the identifications listed below exist. If there 
are any such files, rename them; otherwise they will be replaced in steps 6 
and 7. The files that are created on each disk are: 



Filename 


Filetype 


Disk 


APL 


EXEC 


AandY 


APL 


MODULE 


AandY 


APLCVCMS 


EXEC 


AandY 


APLCVCMS 


MODULE 


A and Y 


APLCVRPQ 


EXEC 


AandY 


APLCVRPQ 


MODULE 


AandY 


APLIBTAB 


APLIBTAB 


AandY 


APLMAC 


MACLIB 


AandY 


APL100 


TEXT 


AandY 


APL101 


TEXT 


A and Y 


APL110 


TEXT 


AandY 


APL111 


TEXT 


AandY 


APL123 


TEXT 


A 


APLMAIN 


MODULE 


Ai 


APL 


MAP 


A 


APLCVCMS 


MAP 


A 


APLCVRPQ 


MAP 


A 


macro-name 2 


MACRO 


A 


APLINSTL 


EXEC 


A 


module-name 3 


TEXT 


A 


APFNS 


W0000002 


Y 


APLCOURS 


W0000001 


Y 


CONVERT 


W0000001 


Y 


EXAMPLES 


W0000001 


Y 


FORMAT 


W0000001 


Y 


HOWEDITS 


W0000001 


Y 


MEDIT 


W0000001 


Y 


NEWS 


W0000001 


Y 


PLOT 


W0000001 


Y 


PRINT 


W0000002 


Y 


SBIC 


W0000001 


Y 


SEDIT 


W0000001 


Y 


TYPEDRIL 


W0000001 


Y 


WSFNS 


W0000001 


Y 



1 Created only when VS APL is installed as a shared system. 

2 There is a macro file for each macro listed in Appendix A under "Auxiliary Processor Macros." 

3 There is a text file for each module listed in Appendix A under "CMS Executor Modules," "Interpreter 
Modules,'* "Shared Storage Manager Modules," and "CMS Conversion Modules." 

5. Ask the system operator to mount the distribution tape and to attach the 
tape drive as virtual device 181, 182, 183, or 184. 
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6. Transfer file APLINSTL EXEC (the CMS procedure that builds VS APL) 
from the distribution tape to the A-disk by issuing these CMS commands: 

TAPE REW ( address 
TAPE FSF 3 (address 
TAPE LOAD * * A ( address 

address 

is the symbolic tape identification or the address of the device on which 
the distribution tape is mounted. 

7. Invoke the procedure that builds VS APL by issuing this CMS command: 

APLINSTL 

The procedure is conversational; enter information when prompted to do 
so. The procedure performs the following actions: 

a. Transfers all required text, exec and macro files (distribution tape files 5 
and 6) from the distribution tape to the A-disk. 

b. Transfers the distributed workspace files from the distribution tape to 
the Y-disk (workspaces VSFILES, VSAPLFILE and FULLSCREEN 
which are used only under VSPC, are not transferred). 

c. Generates file APLMAC MACLIB from the auxiliary processor macros. 

d. Copies the following files from the A-disk to the Y-disk: 

• APL EXEC (VS APL startup procedure) 

• APLCVCMS EXEC (APL\360 and APLSV conversion program 
procedure) 

• APLCVRPQ EXEC (APL/CMS conversion program procedure) 

. APLIBTAB APLIBTAB (library table file) 

. APL100 TEXT, APL101 TEXT, APL1 10 TEXT, APL1 1 1 TEXT, 
and APL 123 TEXT (auxiliary processors) 

• APLMAC MACLIB (auxiliary processor macro library) 

e. Creates files APL MODULE (initialization routine and auxiliary 
processor translate tables for shared system; executor, interpreter, and 
shared storage manager for non-shared system), APLMAIN MODULE 
(executor, interpreter, and shared storage manager for shared system), 
APLCVCMS MODULE (APL \ 3 60 and APLSV conversion program), 
and APLCVRPQ MODULE (APL/CMS conversion program). 

f. Copies files APL MODULE, APLCVCMS MODULE, and 
APLCVRPQ MODULE from the A-disk to the Y-disk. 

A REGEN option, which is available in response to a prompt, causes the 
procedure the perform only actions e and f . The REGEN option can be 
used to recreate the module files after updated text files have been copied 
to the A-disk or to recreate a shared system at a different load address. 
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8. If installing VS APL as a shared system, define the system to CP and then 
load it and save it as follows: 

a. Define the system to be saved by adding a NAMESYS macro to your 
installation's DMKSNT ASSEMBLE module. Code the macro as 
follows: 

APLMAIN NAMESYS SYSNAME=APLMAIN, 
SYSSIZE=172K, 
VSYSADR=IGNORE, 
VSYSRES=, 
SYSCYL=, 

SYSVOL=serial-number, ' 
SYSSTRT=( cylinder, page ) , 2 
SYSPGCT=48, 
SYSPGNM=( 128-175 ),-' 
SYSHRSG=( 8,9, 10)3 

' Provide the serial number of ihe volume on which space was allocated. in slep 2. 

2 Provide the starting cylinder and page address of the space allocated in step 2. 

-> The page and segment numbers shown arc based on a load address of 5I2K. Provide the numbers 
thai correspond to the load address you selected in step 2. 

b. Assemble the new system name table (DMKSNT) by using the 
GENERATE EXEC procedure as described in IBM Virtual Machine 
Facility/ 3 70: Planning and System Generation Guide. 

c. Using a virtual machine large enough to contain the system to be saved 
(load address plus 400K), load the system and save it: 

LOADMOD APLMAIN 
SAVESYS APLMAIN 

d. Before continuing with step 9, log on to VM/370 with a smaller virtual 
machine (of a size no greater than the saved system's load address). 

9. Test that VS APL is installed correctly by executing the sample terminal 
session (see Appendix B). 

This completes the installation procedure. The A-disk should be kept for 
backup and maintenance of the system. The distributed workspaces must be 
kept on the Y-disk; that is, on the disk that is accessed as a Y-disk by VS 
APL users. The other files on the Y-disk (see list in step 4 above) can also be 
kept there or they can be transferred to the CMS system disk. 
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INSTALLING VS APL UNDER OS/VS (VSPC) 



This section describes how to install VS APL as a foreground processor under 
either OS/VS 1 (VSPC) or OS/VS2 (VSPC). 



Requirements for Installation 

The facilities required for installing VS APL under OS/VS are: 

A System/370 machine configuration that can support OS/VS 1 (VSPC) 
or OS/VS2 (VSPC). 

An installed release of OS/VS 1 (VSPC) or OS/VS2 (VSPC). 

OS/VS Linkage Editor; utility programs IEBPTPCH, IEHPROGM, and 
IEBUPDTE; and job control program IEFBR14. 

A region large enough to run the VSPC Service Program and the OS/VS 
Linkage Editor. 

A magnetic tape device. 

The VS APL distribution tape. 

Space in OS/VS 1 SYS1.LINKLIB or OS/VS2 SYS1.LPALIB for the VS 
APL load module (see "Auxiliary Storage Requirements"). 

Space in OS/VS private libraries for the VS APL object decks and the 
conversion program load module (see "Auxiliary Storage Requirements"). 

Space in VSPC public libraries for the distributed workspaces (see 
"Auxiliary Storage Requirements"). 

Authorization to update OS/VS 1 SYS1.LINKLIB or OS/VS2 
SYS1.LPALIB. 

Authorization as a VSPC chief administrator. 

A terminal supported by VSPC (required only to execute the sample 
terminal session). 



Overview of Installation Procedure 



In brief, the procedure for installing VS APL under OS/VS (VSPC) is as 
follows. The procedure is described in detail in the next section. 

1 . Punch the sample JCL from the distribution tape. 

2. Allocate space for and catalog the data sets required for installing VS APL: 
VSAPL.OBJLIB and VSAPL.CNVTLIB. 

3. Transfer object modules from the distribution tape to data set 
VSAPL.OBJLIB. 

4. Link-edit the VS APL load module. 

5. Link-edit the conversion program into data set VSAPL.CNVTLIB. 
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Installation Procedure 



6. Run the VSPC Service Program to define VS APL, public libraries 1 and 2, 
and the internal auxiliary processors to VSPC and to transfer the 
distributed workspaces to the VSPC libraries. 

7. Test that VS APL is installed correctly by executing the sample terminal 
session (see Appendix C). 



Punch the OS/VS sample JCL procedures from the VS APL distribution 
tape by executing the following job: 

account ing- information , MSGLEVEL= 1 

PGM=IEBPTPCH 

SYSOUT=A 

DSN=JCL , VOL=SER=APLDTR , UNIT=2400 , 

DISP=OLD,LABEL=( 3,NL), 

DCB=( LRECL=80 , BLKSIZE=80 , RECFM=F ) 

SYSOUT=B 

* 



There are six jobs in the sample JCL. The first five are used for each of the 
next five steps of the installation procedure. The last one is used to run the 
conversion program (see "OS/VS Workspace Conversion Program"). 

It may be necessary to alter the sample JCL to suit your requirements. In 
each step, the sample JCL is listed, and the modifications that may be 
required are noted. In this step and in steps 3 and 6, group name 2400 is 
used as the UNIT parameter to. mean any magnetic tape device. In steps 4 
and 5, group name SYSDA is used as the UNIT parameter to mean any 
direct access device. If either of these names is not so defined for your 
installation, these parameters must be altered. 

2. Allocate space for two partitioned data sets and catalog them: 

• VSAPL.OBJLIB, object module library for the executor, interpreter, 
and conversion program. 

• VSAPL.CNVTLIB, load module library for the conversion program. 



//PUNCHJCL JOB 


// 


EXEC 


//SYSPRINT 


DD 


//SYSUT1 


DD 


// 




// 




//SYSUT2 


DD 


//SYSIN 


DD 


PUNCH 




/* 
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Execution of job ALLOC from the sample JCL, altered to suit your 
requirements, accomplishes this step. Supply the information shown in 
lowercase below. 

account ing-informat ion ,MSGLEVEL=1 

PGM=IEFBR14 

DSN=VSAPL . OBJLIB , DISP=( NEW , KEEP ) , 

VOL=SER=volser , UNIT=typeunit , 

SPACE=(3200,( 143,5,20) ), 

DCB=( LRECL=80 , BLKSIZE=3200 , RECFM=FB ) 

DSN=VSAPL . CNVTLIB , DISP=( NEW , KEEP ) , 

VOL=SER=volser , UNIT=typeunit , 

SPACE=(CYL,( 1,1,1)) 

PGM=IEHPROGM 

SYSOUT=A 

* 

VSAPL. OBJLIB, VOL=typeunit=volser 
VSAPL . CNVTLIB , VOL=typeuni t=volser 
/* 

3. Transfer files 5 and 7 from the VS APL distribution tape to data set 
VSAPL.OBJLIB. Execution of job BUILDOBJ from the sample JCL, 
altered to suit your requirements, accomplishes this step. Supply the 
information shown in lowercase below. 

Each input file is a series of object modules, each preceded by a ./ ADD 
NAME= statement. The BUILDOBJ job reads the two files and writes 
each object module as a member of VSAPL.OBJLIB. 



//ALLOC 




JOB 


// 




EXEC 


//DD1 




DD 


// 






// 






// 






//DD2 




DD 


// 






// 






// 




EXEC 


//SYSPRINT 


DD 


//SYSIN 




DD 


CATLG 


DSNAME= 


CATLG 


DSNAME= 


/* 







//BUILDOBJ JOB 

// EXEC 

//SYSPRINT DD 

//SYSUT2 DD 

//SYSIN DD 

// 

// 

// EXEC 

//SYSPRINT DD 

//SYSUT2 DD 

//SYSIN DD 

// 

// 

/* 



accounting-information, MSGLEVEL=1 

PGM=IEBUPDTE , PARM=NEW 

SYSOUT=A 

DSN=VSAPL . OBJLIB , DISP=OLD 

DSN=INTERP . OBJECT , VOL=SER=APLDTR , 

UNIT=2400 , DISP=( OLD , PASS ) , LABEL=( 5 , NL ) , 

DCB=( LRECL=80 , BLKSIZE=3200 , RECFM=FB ) 

PGM=IEBUPDTE , PARM=NEW 

SYSOUT=A 

DSN=VSAPL . OBJLIB , DISP=OLD 

DSN=OSVS . DEPENDNT . OBJECT , VOL=SER=APLDTR , 

UNIT=2400 , DISP=OLD , LABEL=( 7 , NL ) , 

DCB=(LRECL=80,BLKSIZE=3200,RECFM=FB) 
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4. Link-edit the VS APL load module. Execution of job LINKAPL from the 
sample JCL, altered to suit your requirements, accomplishes this step. The 
job contains two SYSLMOD DD statements, one to link-edit VS APL into 
SYS1.LINKLIB for OS/VS1 and another to link-edit VS APL into 
SYS1.LPALIB for OS/VS2. Remove the statement that does not apply to 
your operating system, and supply the information shown in lowercase 
below. 

The link-edit map output from this step should be saved. 

//LINKAPL JOB accounting-information, MSGLEVEL=1 

// EXEC PGM=HEWL, 

// PARM=' RENT, NCAL, LIST, MAP ,XREF' 

//SYSPRINT DD SYSOUT=A 

//OBJLIB DD DSN=VSAPL. OBJLIB, DISP=SHR 

//SYSLMOD DD DSN=SYS1 . LINKLIB,DISP=OLD (OS/VS1 ONLY) 

//SYSLMOD DD DSN=SYS1 . LPALIB, DISP=OLD ( OS/VS2 ONLY) 

//SYSUT1 DD UNIT=SYSDA,SPACE=(TRK,(40,10) ) 

//SYSLIN DD * 
INCLUDE OBJLIB(M 



ENTRY APLPCOEX 
SETCODE AC( 1 ) 
NAME APLPCOEX(R) 
/* 

1 The sample JCL contains an INCLUDE statement for each module listed in Appendix A under " VSPC 
Executor Modules" and "Interpreter Modules." 

5. Link-edit the conversion program into data set VSAPL.CNVTLIB. 
Execution of job LINKCNVT from the sample JCL, altered to suit your 
requirements, accomplishes this step. Supply the information shown in 
lowercase below. 

The link-edit map output from this step should be saved. 

//LINKCNVT JOB accounting-information, MSGLEVEL=1 

// EXEC PGM=HEWL,PARM='NCAL,LIST,MAP,XREF,REUS' 

//SYSPRINT DD SYSOUT=A 

//OBJLIB DD DSN=VSAPL. OBJLIB, DISP=SHR 

//SYSLMOD DD DSN=VSAPL. CNVTLIB,DISP=OLD 

//SYSUT1 DD UNIT=SYSDA,SPACE=(TRK,(40, 10) ) 

//SYSLIN DD * 
INCLUDE OBJLIB( 1 ) 



ENTRY COIBM 
NAME APLCVOS(R) 
/* 

1 The sample JCL contains an INCLUDE statement for each module listed in Appendix A under 
"VSPC/OS Conversion Modules." 
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6. Run the VSPC Service Program to: 

• Define VS APL as a foreground processor. 

• Define public libraries 1 and 2. 

• Define the distributed auxiliary processors. 

• Transfer the distributed workspaces from the distribution tape to 
libraries 1 and 2 (workspaces APFNS and PRINT, which are used only 
under CMS, are not transferred). 

Execution of job VSPCSERV from the sample JCL, altered to suit your 
requirements, accomplishes this step. Supply the information shown in 
lowercase below. Although files 8 through 16 of the distribution tape 
contain 800-byte unblocked records, they must be described as 80-byte 
blocked records to the IMPORT function of the VSPC Service Program. 
See VSPC Installation Reference Material for a description of the VSPC 
Service Program and control statements. 

account ing-informat ion, MSGLEVEL=1 
PGM=ASUSPEXC, PARM=NOLIST 
DSN=name , DISP=OLD 
DSN=name , DISP=OLD 
DSN=name , DISP=OLD 
DSN=NEWS , VOL=SER=APLDTR , 

UNIT=2400,DISP=( OLD, PASS ) , LABEL=( 8 ,NL ) , 
DCB=( LRECL=80 , BLKSIZE=800 , RECFM=FBS ) 
DSN=WSFNS , VOL=SER=APLDTR , 
UNIT=2400,DISP=( OLD, PASS ) ,LABEL=( 9,NL) , 
DCB=( LRECL=80 , BLKSIZE=800 , RECFM=FBS ) 
DSN=CONVERT , VOL=SER=APLDTR , 
UNIT=2400,DISP=( OLD, PASS ),LABEL=( 10,NL), 
DCB=(LRECL=80,BLKSIZE=800,RECFM=FBS) 
DSN=TYPEDRIL , VOL=SER=APLDTR , 
UNIT=2400,DISP=( OLD, PASS ),LABEL=( 1 1 ,NL), 
DCB=( LRECL=80 , BLKSIZE=800 , RECFM=FBS ) 
DSN=APLCOURS , VOL=SER=APLDTR, 
UNIT=2400,DISP=( OLD, PASS ),LABEL=( 12,NL), 
DCB=( LRECL=80 , BLKSIZE=800 , RECFM=FBS ) 
DSN=PLOT , VOL=SER=APLDTR , 

UNIT=2400 , DISP=( OLD , PASS ) , LABEL=( 1 3 , NL ) , 
DCB=( LRECL=80 , BLKSIZE=800 , RECFM=FBS ) 
DSN=EXAMPLES , VOL=SER=APLDTR , 
UNIT=2400,DISP=( OLD, PASS ),LABEL=( 14,NL), 
DCB=(LRECL=80,BLKSIZE=800,RECFM=FBS) 
DSN=FORMAT , VOL=SER=APLDTR , 
UNIT=2400,DISP=( OLD, PASS ),LABEL=( 15,NL), 
DCB=( LRECL=80 , BLKSIZE=800 , RECFM=FBS ) 
DSN=MEDIT , VOL=SER=APLDTR , 

UNIT=2400,DISP=( OLD, PASS ),LABEL=( 16,NL), 
DCB=( LRECL=80 , BLKSIZE=800 , RECFM=FBS ) 
DSN=SEDIT , VOL=SER=APLDTR , 

UNIT=2400,DISP=( OLD, PASS ),LABEL=( 17,NL), 
DCB=(LRECL=80,BLKSIZE=800,RECFM=FBS ) 



//VSPCSERV 


JOB 


// 


EXEC 


//SYSOLDIR 


DD 


//SYSOLIB1 


DD 


//SYSOLIB2 


DD 


//NEWS 


DD 


// 




// 




//WSFNS 


DD 


// 




// 




//CONVERT 


DD 


// 




// 




//TYPEDRIL 


DD 


// 




// 




//APLCOURS 


DD 


// 




// 




//PLOT 


DD 


// 




// 




//EXAMPLES 


DD 


// 




// 




//FORMAT 


DD 


// 




// 




//MEDIT 


DD 


// 




// 




//SEDIT 


DD 


// 




// 
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//HOWEDITS 


DD 


// 




// 




//SBIC 


DD 


// 




// 




//VSFILES 


DD 


// 




// 




//VSAPLFIL 


DD 


// 




// 




//FULLSCRE 


DD 


// 




// 




//SYSPRINT 


DD 


//SYSIN 


DD 



DSN=HOWEDITS , VOL=SER=APLDTR , 
UNIT=2400 , DISP=( OLD , PASS ) , LABEL=( 1 8 , NL ) , 
DCB=( LRECL=80 , BLKSIZE=800 , RECFM=FBS ) 
DSN=SBIC , VOL=SER=APLDTR , 

UNIT=2400,DISP=( OLD, PASS ),LABEL=( 19,NL), 
DCB=( LRECL=80 , BLKSIZE=800 , RECFM=FBS ) 
DSN=VSFILES , VOL=SER=APLDTR , 
UNIT=2400,DISP=( OLD, PASS ),LABEL=( 20,NL), 
DCB=( LRECL=80 , BLKSIZE=800 , RECFM=FBS ) 
DSN=VSAPLFIL , VOL=SER=APLDTR , 
UNIT=2400,DISP=OLD,LABEL=( 21 ,NL), 
DCB=( LRECL=80 , BLKSIZE=800 , RECFM=FBS ) 
DSN=FULLSCRE , VOL=SER=APLDTR , 
UNIT=2400 , DISP=OLD , LABEL=( 22 , NL ) , 
DCB=(LRECL=80,BLKSIZE=800,RECFM=FBS) 
SYSOUT=A 
* 

AUTH chief-administrator-number/password 

DEFINE FP NAME(APL) CODE(AO) ENTRY ( APLPCOEX ) 

DEFINE USER( 1 ) PASSWORD( password ) LIBTYPE( PUBLIC C)- 

SPACE( 1 000 ) PROJLIB( NONE ) CONTENT( APL ) INTPRMAX( 60 30 ) 
DEFINE USER(2) PASSWORD( password ) LIBTYPE( PUBLIC C)- 

SPACE(1000) PROJLIB( NONE ) CONTENT ( APL ) INTPRMAX( 60 30) 
DEFINE AP(121) NOPASS SSMAX( 4000000 30) 
DEFINE AP(122) NOPASS SSMAX( 4058 30) 
DEFINE AP(123) NOPASS SSMAX( 32767 30) 
DEFINE AP(124) NOPASS SSMAX( 4096 30) 
AUTH 1 /password 

IMPORT 1 NEWS TYPE (OBJECT) CONTENT ( APL ) 
IMPORT 1 WSFNS TYPE( OBJECT) CONTENT(APL) 
IMPORT 1 CONVERT TYPE ( OBJECT ) CONTENT(APL) 
IMPORT 1 TYPEDRILL TYPE( OBJECT) CONTENT(APL) 
IMPORT 1 APLCOURSE TYPE ( OBJECT ) CONTENT (APL) 
IMPORT 1 PLOT TYPE (OBJECT) CONTENT (APL) 
IMPORT 1 EXAMPLES TYPE( OBJECT ) CONTENT ( APL ) 
IMPORT 1 FORMAT TYPE (OBJECT) CONTENT (APL) 
IMPORT 1 MEDIT TYPE( OBJECT) CONTENT(APL) 
IMPORT 1 SEDIT TYPE( OBJECT) CONTENT ( APL ) 
IMPORT 1 HOWEDITS TYPE( OBJECT ) CONTENT ( APL ) 
IMPORT 1 SBIC TYPE( OBJECT) CONTENT ( APL ) 
AUTH 2/password 

IMPORT 2 VSFILES TYPE( OBJECT) CONTENT(APL) 
IMPORT 2 VSAPLFILE TYPE( OBJECT) CONTENT ( APL ) 
IMPORT 2 FULLSCREEN TYPE( OBJECT) CONTENT(APL) 
/* 

7. Test that VS APL is installed correctly by executing the sample terminal 
session (see Appendix C). 
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INSTALLING VS APL UNDER DOS/VS (VSPC) 

This section describes how to install VS APL as a foreground processor under 
DOS/VS (VSPC). 

Requirements for Installation 

The facilities required for installing VS APL under DOS/VS are: 

• A System/370 machine configuration that can support DOS/VS (VSPC). 

• An installed release of DOS/VS (VSPC). 

• The following DOS/VS system and utility programs: 

- CORGZ 

- DSTRB 

- LNKEDT 

- MAINT 

• A partition large enough to run the VSPC Service Program and the above 
utility programs. 

• Two magnetic tape devices or one direct access storage device. 

• The VS APL distribution tape or distribution disk. 

• Space available for private relocatable libraries, core image libraries, VS 
APL object decks, and VS APL link-edited modules (see "Auxiliary 
Storage Requirements"). 

• Space in VSPC public libraries for the distributed workspaces (see 
"Auxiliary Storage Requirements"). 

• Authorization as a VSPC chief administrator. 

• A terminal supported by VSPC (required only to execute the sample 
terminal session). 

Overview of Installation Procedure 

In brief, the procedure for installing VS APL under DOS/VS (VSPC) is as 
follows. The procedure is described in detail in the next section. 

1. Punch the sample JCL from the distribution tape or distribution disk. 

2. If private libraries are desired, define a private relocatable library for the 
APL object decks and a private core image library for the APL foreground 
processor module and APL workspace conversion program. 

3. Deblock the object decks from the distribution tape or distribution disk 
onto another tape or disk file, and catalog them into the relocatable library. 

4. Link-edit the APL foreground processor and workspace conversion 
programs into the core image library. 

5. Run the VSPC Service Program to define VS APL, public libraries 1 and 2, 
and the internal auxiliary processors to VSPC and to transfer the 
distributed workspaces to the VSPC libraries. 

6. Test that VS APL is installed correctly by executing the sample terminal 
session (see Appendix C). 
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Installation Procedure 



1. Punch the DOS/VS sample JCL from the VS APL distribution tape by 
executing the following job: 

// JOB PNCHSAMP 

// ASSGN SYS004,TAPE Distribution Tape 

// ASSGN SYS005,X'00D' 

// EXEC DSTRB 

// UDS COP 

// END 

A 

Punch the DOS/VS sample JCL from the VS APL distribution disk by 
executing the following job: 

// JOB PNCHSAMP 

// ASSGN SYS004, unit, VOL=1 1 1 111 , SHR Distribution Disk 

// DLBL UIN, 'A5748AP1 . DOSVSJCL. VSAPL 1 ,99/365, SD 

//EXTENT SYS004 

// ASSGN SYS005,X'00D' 

// EXEC DSTRB 

// UDS COP 

// END 

A 

There are several DOS/VS jobs in the sample JCL. It may be necessary to 
alter the sample JCL to suit your requirements. In each step the sample 
JCL is listed, and the modifications that may be required are noted. In this 
step, the word unit is used to represent the unit type of the distribution 
disk. In other steps, the words devicetype, and volserial are used to 
represent the DOS/VS device type and volume serial number, respectively. 
For those steps, you should supply the DOS/VS device type and volume 
serial number that is appropriate to your installation. The volume serial 
number of the distribution disk is always 111111. 

2. If private libraries are desired, define a private relocatable library for the 
APL object decks and a private core image library for the APL forground 
processor and APL workspace conversion program. If private libraries are 
not desired, skip to step 3. 

Execution of job ALLOCRLB from the sample JCL, altered to suit your 
requirements, can be used to define a new private relocatable library. 
Supply the information in lowercase below. 

// JOB ALLOCRLB 

// ASSGN SYSRLB, devicetype, VOL=volserial, SHR 

// DLBL IJSYSRL,'VS APL PRIV RLB ', 99/365 , SD 

// EXTENT SYSRLB, volserial, 1 ,0, first-track, total-tracks 

// EXEC CORGZ 

NEWVOL RL=cylinders( directory-tracks ) 
/* 

A 

Execution of job ALLOCCIL from the sample JCL, altered to suit your 
requirements, can be used to define a new private core image library. 
Supply the information in lowercase below. 

// JOB ALLOCCIL 

// ASSGN SYS003, devicetype, VOL=volserial, SHR 
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// DLBL IJSYSPC,'VS APL PRIV CIL ', 99/365 , SD 

// EXTENT SYS003,volserial, 1 ,0, first-track, total-tracks 

// EXEC CO'RGZ 

NEWVOL CL=cylinders( directory-tracks ) 
/* 

A 

The space required in the relocatable and core image libraries is given in 
the section "Storage Requirements." 

3. Deblock the object decks from the distribution tape or distribution disk 
onto another (possibly temporary) tape or disk file. Clear space in the 
system or private relocatable library by deleting all VS APL object decks 
and by condensing the library. Then, catalog the deblocked object decks 
into the relocatable library. 

Execution of job TAPEDEBL from the sample JCL, altered to suit your 
requirements, accomplishes this step using a distribution tape. The 
deblocked output will be on tape. Supply the information in lowercase 
below. 

// JOB TAPEDEBL 

// ASSGN SYS004,TAPE Input Distribution Tape 

// ASSGN SYS005,TAPE Output Tape 

// UPSI 10100 

// EXEC DSTRB Deblock object file 

// UDS DBL 

// END 

// MTC WTM,SYS005 

// MTC REW,SYS005 

* REMOVE FOLLOWING THREE CARDS IF SYSTEM RLB IS USED 

// ASSGN SYSRLB,devicetype,VOL=volserial,SHR 

// DLBL IJSYSRL,'VS APL PRIV RLB ', 99/365 , SD 

// EXTENT SYSRLB 

// EXEC MAINT Delete VS APL OBJ and condense 

DELETR 1 



CONDS RL 

/* 

// ASSGN SYSIPT,SYS005 SYSIPT is deblocked OBJ 

// EXEC MAINT Catalog deblocked OBJ 

A 

Execution of job DISKDEBL from the sample JCL, altered to suit your 
requirements, accomplishes this step using a distribution disk. The 
deblocked output will be on disk. Supply the information in lowercase 
below. 

// JOB DISKDEBL 

// ASSGN SYS004,devicetype,VOL=1 1 1 11 1 ,SHR 

// DLBL UIN, 'A5748AP1 . DOSVSOBJ . VSAPL ' ,* 99/365 , SD 

// EXTENT SYS004 

// ASSGN SYS005,devicetype,VOL=volserial,SHR 

// DLBL UOUT, ' VSAPL. DEBLK. OBJECT' , , SD 

* The sample JCL contains a DELETR statement for each module listed in 
Appendix A under "VSPC Executor Modules," "Interpreter Modules," and 
"VSPC/DOS Conversion Modules." 
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// EXTENT SYS005,volserial,1 ,0, first-track, total-tracks 
// EXEC DSTRB 

// UDS DBL Deblock object file 

// END 

* REMOVE FOLLOWING THREE CARDS IF SYSTEM RLB IS USED 
// ASSGN SYSRLB,devicetype,VOL=volserial,SHR 
// DLBL IJSYSRL, ' VS APL PRIV RLB ', 99/365 , SD 
// EXTENT SYSRLB 

// EXEC MAINT Delete VS APL object and condense 

DELETR' 



CONDS RL 

/* 

// ASSGN SYS006,SYSIPT Store SYSIPT for later restoration 

// DLBL I JSYSIN, ' VSAPL. DEBLK. OBJECT' 
// EXTENT SYSIPT 

ASSGN SYSIPT, SYS005 SYSIPT is deblocked object 

// EXEC MAINT Catalog deblocked object 

CLOSE SYSIPT, UA 

ASSGN SYSIPT, SYS006 Restore SYSIPT 

A 

' The sample JCL contains a DELETR statement for each module listed in Appendix A under "VSPC 
Executor Modules," "Interpreter Modules," and "VSPC/DOS Conversion Modules." 

4. Link-edit the VS APL foreground processor and workspace conversion 
modules into the core image library. 

Execution of job LINKAPL, altered to suit your requirements, 
accomplishes this step. This job will first delete the appropriate phases and 
then condense the core image library. You should remove the appropriate 
ASSGN, DLBL, and EXTENT statements from the sample JCL if the 
system core image library or the system relocatable library is to be used. 
Supply the information in lowercase below. 

// JOB LINKAPL 

* REMOVE FOLLOWING THREE STATEMENTS IF 

* SYSTEM CORE IMAGE LIB IS USED 

// DLBL IJSYSPC,'VS APL PRIV CIL',,SD 
// EXTENT SYSCLB 

ASSGN SYSCLB, devicetype,VOL=volserial , SHR 
// EXEC MAINT 

DELETC APLPCOEX,APLCVDOS 

CONDS CL 

/* 

* REMOVE FOLLOWING THREE STATEMENTS IF 

* SYSTEM RLB IS USED 

// ASSGN SYSRLB, devicetype ,VOL=volserial , SHR 

// DLBL IJSYSRL, 'VS APL PRIV RLB',,SD 

// EXTENT SYSRLB 

// OPTION CATAL 

ACTION REL , CLEAR , MAP , NOAUTO VSPC/DOS workspace conversion 
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PHASE APLCVDOS , S , NOAUTO modules 

INCLUDE' 



ENTRY COIBM 

PHASE APLPCOEX , S , NOAUTO VS APL foreground processor 

INCLUDE? 



ENTRY APLPCOEX 

/* 

// EXEC LNKEDT 

A 

' The sample JCL contains an INCLUDE statement for each module listed in Appendix A under 
"VSPC/DOS Conversion Modules." 

- The sample JCL contains an INCLUDE statement for each module listed in Appendix A under "VSPC 
Executor Modules" and "Interpreter Modules." The INCLUDE statements arc ordered to minimize 
paging. 

5. Run the VSPC Service Program to: 

• Define VS APL as a foreground processor. 

• Define public libraries 1 and 2. 

• Define the distributed auxiliary processors. 

• Transfer the distributed workspaces from the distribution tape or disk to 
libraries 1 and 2 (workspace APFNS and workspace PRINT, which are 
used only under CMS are not transferred). 

Execution of job VSPCSRVT from the sample JCL, altered to suit your 
requirements, accomplishes this step for the distribution tape. Execution of 
job VSPCSRVD, similarly altered, accomplishes this step for the 
distribution disk. Supply the information in lowercase below. (The term 
'file-id' represents the identification of the file, such as the VSAM master 
catalog or VSPC directory, that was assigned when VSPC was installed.) 
Both of these jobs assume that the VSAM master catalog was permanently 
assigned at IPL time and that you are using a VSAM user catalog. The user 
catalog, the VSPC directory, and VSPC library data sets are assumed to 
reside on the same volume (which is assigned arbitrarily to SYS001). See 
VSPC Installation Reference Material for a description of the VSPC 
Service Program and VSPC libraries. 

// JOB VSPCSRVT 

// OPTION LISTX 

// ASSGN SYS004,TAPE Distribution tape 

// MTC REW,SYS004 

// MTS FSF,SYS004,7 

// DLBL IJSYSCT, 'file-id' ,, VSAM VSPC master catalog 

// EXTENT SYSCAT 

// ASSGN SYS001 ,devicetype,VOL=volserial VSPC library disk 

// DLBL IJSYSUC, 'file-id* , ,VSAM VSAM user catalog 

// EXTENT SYS001 

// DLBL IJSYSOD, 'file-id' ,, VSAM VSPC directory 

// EXTENT SYS001 

// DLBL IJSYS01 , 'file-id' ,, VSAM VSPC library 

// EXTENT SYS001 

// DLBL IJSYS02, 'file-id' ,, VSAM VSPC library 
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IMPORT 1 
IMPORT 1 
IMPORT 1 
IMPORT 1 
IMPORT 1 
IMPORT 1 
IMPORT 1 
IMPORT 1 



// EXTENT SYS001 

// EXEC ASUSPEXC 

AUTH chief -administrator-number/password 

DEFINE FP name(APL) CODE(AO) ENTRY ( APLPCOEX ) 

DEFINE USER( 1 ) PASSWORD( password ) LIBTYPE( PUBLIC C )- 

SPACE(IOOO) PROJLIB( NONE ) CONTENT! APL) INTPRMAXt 60 30) 
DEFINE USERt 2 ) PASSWORD! password ) LIBTYPE( PUBLIC C)- 

SPACE(1000) PROJLIB( NONE ) CONTENT! APL ) INTPRMAX( 60 30) 
DEFINE AP(121) NOPASS SSMAX( 4000000 30) 
DEFINE AP(122) NOPASS SSMAX( 4058 30 ) 
DEFINE AP(123) NOPASS SSMAX( 32767 30) 
DEFINE AP(124) NOPASS SSMAX( 4096 30) 
ENVIRONMENT DEVICE( 2400 004 NOREWIND ) NOLABEL- 

FORMAT( F ) BLOCKSIZE( 800 ) RECORDSIZE( 80 ) 
AUTH 1 /password 

IMPORT 1 NEWS TYPE( OBJECT) CONTENT( APL ) 
IMPORT 1 WSFNS TYPE( OBJECT ) CONTENT( APL ) 
IMPORT 1 CONVERT TYPE( OBJECT ) CONTENT! APL ) 
IMPORT 1 TYPEDRILL TYPE( OBJECT ) CONTENT( APL ) 

APLCOURSE TYPE( OBJECT) CONTENT( APL ) 

PLOT TYPE( OBJECT) CONTENT( APL ) 

EXAMPLES TYPE( OBJECT) CONTENT( APL ) 

FORMAT TYPE( OBJECT ) CONTENTt APL ) 

MEDIT TYPE( OBJECT) CONTENTt APL ) 

SEDIT TYPEt OBJECT) CONTENT( APL ) 

HOWEDITS TYPE( OBJECT) CONTENTt APL ) 

SBIC TYPEt OBJECT) CONTENTt APL ) 
AUTH 2/password 

IMPORT 2 VSFILES TYPEt OBJECT ) CONTENTt APL ) 
IMPORT. 2 VSAPLFILE TYPEt OBJECT ) CONTENTt APL ) 
IMPORT 2 FULLSCREEN TYPEt OBJECT ) CONTENTt APL ) 
/* 

A 

// JOB VSPCSRVD 

// OPTION LISTX 

// ASSGN SYS004,devicetype,VOL=1 1 1 1 11 ,SHR 

// DLBL NEWS, 'A5748AP1 .NEWS. VSAPL' ,99/365, SD 

// EXTENT SYS004 

// DLBL WSFNS, 'A5748AP1 .WSFNS. VSAPL' ,99/365, SD 

// EXTENT SYS004 

// DLBL CONVERT, 'A5748AP1 .CONVERT. VSAPL' ,99/365, SD 

// EXTENT SYS004 

// DLBL TYPEDRI, 'A5748AP1 .TYPEDRIL. VSAPL' ,99/365, SD 

// EXTENT SYS004 

// DLBL APLCOUR, 'A5748AP1 .APLCOURS. VSAPL* ,99/365, SD 

// EXTENT SYS004 

// DLBL PLOT, 'A5748AP1 .PLOT. VSAPL' ,99/365, SD 

// EXTENT SYS004 

// DLBL EXAMPLE, 'A5748AP1 .EXAMPLES. VSAPL' ,99/365, SD 

// EXTENT SYS004 

// DLBL FORMAT, 'A5748AP1 .FORMAT. VSAPL' ,99/365, SD 

// EXTENT SYS004 

// DLBL MEDIT, 'A5748AP1 .MEDIT. VSAPL 1 , 99/365, SD 

// EXTENT SYS004 
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// DLBL SEDIT, 'A5748AP1 . SEDIT . VSAPL ' , 99/365, SD 

// EXTENT SYS004 

// DLBL HOWEDIT, 'A5748AP1 .HOWEDITS. VSAPL' ,99/365, SD 

// EXTENT SYS004 

// DLBL SBIC, 'A5748AP1 .SBIC. VSAPL' ,99/365, SD 

// EXTENT SYS004 

// DLBL VSFILES, 'A5748AP1 .VSFILES. VSAPL' ,99/365, SD 

// EXTENT SYS004 

// DLBL VSAPLFI, 'A5748AP1 .VSAPLFIL. VSAPL' ,99/365, SD 

// EXTENT SYS004 

// DLBL FULLSCR, 'A5748AP1 .FULLSCRE. VSAPL' ,99/365, SD 

// EXTENT SYS004 

// DLBL IJSYSCT, 'file-id' , ,VSAM VSAM master catalog 

// EXTENT SYSCAT 

// ASSGN SYS001 , devicetype, VOL=volser ial VSPC library disk 

// DLBL IJSYSUC, 'f ile-id' , , VSAM VSAM user catalog 

// EXTENT SYS001 

// DLBL IJSYSOD, 'file-id' ,, VSAM VSPC directory 

// EXTENT SYS001 ,volserial 

// DLBL IJSYS01 , ''file-id' ,, VSAM VSPC library 

// EXTENT SYS001 ,volserial 

// DLBL IJSYS02, 'file-id' ,, VSAM VSPC library 

// EXTENT SYS001 ,volserial 

// EXEC ASUSPEXC 

AUTH chief -administrator-number/password 

DEFINE FP NAME(APL) CODE( AO ) ENTRY ( APLPCOEX ) 

ENVIRONMENT DEVICE( distribution-device ) FORMAT! FB)- 

BLOCKSIZE( 800 ) RECORDSIZE( 80 ) 
DEFINE USER( 1 ) PASSWORD( password ) LIBTYPEt PUBLIC C )- 

SPACE(1000) PROJLIB( NONE) CONTENT! APL) INTPRMAX! 60 30) 
DEFINE USER( 2 ) PASSWORD( password ) LIBTYPEt PUBLIC C)- 

SPACE(1000) PROJLIB(NONE) CONTENT! APL ) INTPRMAXf 60 30) 
DEFINE AP(121) NOPASS SSMAX( 4000000 30) 
DEFINE AP(122) NOPASS SSMAX( 4058 30) 
DEFINE AP(123) NOPASS SSMAX( 32767 30) 
DEFINE AP(124) NOPASS SSMAX( 4096 30) 
AUTH 1 /password 

IMPORT 1 NEWS TYPE( OBJECT ) CONTENT( APL ) 
IMPORT 1 WSFNS TYPE( OBJECT) CONTENT( APL ) 
IMPORT 1 CONVERT TYPE( OBJECT ) CONTENT! APL ) 
IMPORT 1 TYPEDRILL TYPE( OBJECT ) CONTENT( APL ) 
IMPORT 1 APLCOURSE TYPE (OBJECT) CONTENT! APL ) 
IMPORT 1 PLOT TYPE( OBJECT ) CONTENT( APL ) 
IMPORT 1 EXAMPLES TYPE( OBJECT ) CONTENT! APL ) 
IMPORT l" FORMAT TYPE( OBJECT ) CONTENT! APL ) 
IMPORT 1 MEDIT TYPE! OBJECT) CONTENT! APL ) 
IMPORT 1 SEDIT TYPE! OBJECT) CONTENT! APL ) 
IMPORT 1 HOWEDITS TYPE( OBJECT ) CONTENT! APL ) 
IMPORT 1 SBIC TYPE! OBJECT) CONTENT! APL ) 
AUTH 2/password 

IMPORT 2 VSFILES TYPE( OBJECT ) CONTENT! APL ) 
IMPORT 2 VSAPLFILE TYPE! OBJECT ) CONTENT! APL ) 
IMPORT 2 FULLSCREEN TYPE! OBJECT) CONTENT! APL ) 
/* 

A 
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6. Test that VS APL is installed correctly by executing the sample terminal 
session (see Appendix C). 
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DEFINING VS APL USERS 

This section describes how to define VS APL users to VM/370 and VSPC. 

VM/370 User Directory 

Under CMS, a VS APL user is not defined as such. A VS APL user is a 
VM/370 user who has access to CMS and to VS APL and its libraries. The 
procedure for defining a VM/370 user directory entry is described in IBM 
Virtual Machine Facility/ 370: Operator's Guide. When defining a directory 
entry for a VS APL user, observe these guidelines: 

• The virtual machine must be large enough to execute VS APL (see 
"Virtual Storage Requirements"). If VS APL is installed as a shared 
system, the virtual machine size must be no larger than the load address of 
the shared system. 

• The user's CMS A-disk, in addition to whatever else he may use it for, is 
his VS APL private library. Define a disk at virtual device address 191 with 
sufficient space for anticipated workspace storage (see "Auxiliary Storage 
Requirements for Workspaces"). 

• The CMS Y-disk contains the VS APL public libraries; it can also contain 
other components of the VS APL system. Define a read-only link to this 
disk with virtual device address 19E. 

• Do not define a link to a disk that contains VS APL project libraries. VS 
APL links to a project library disk dynamically as a G-disk with virtual 
device address 197. Defining a link to a project library disk could prevent 
other VS APL users from accessing project libraries. Also, do not define a 
disk with virtual device address 197 for any VS APL user. 

• Define CMS as the system to be loaded when the user logs on. 
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VSPC User Prof Oe 



Under VSPC, a VS APL user is not necessarily defined as such. A VS APL 
user is a VSPC user whose profile includes the options required for using VS 
APL. Use the VSPC DEFINE command or the VSPC Service Program 
DEFINE control statement to define a new user's profile. Use the VSPC 
ALTER command or the VSPC Service Program ALTER control statement 
to modify an existing user's profile. They are described fully in VSPC 
Installation Reference Material. An example of DEFINE operands for a VS 
APL user is: 



Operand 

USER( 123456) 
PAS SWORD (MYP ASS 
LIBTYPE( PRIVATE 
SPACE( 500 ) 

PROJLIB( 512 ) 
CONTENT ( APL ) 



INTPRMAX( 100 50 ) 



Description 

Defines user number and library number 123456. 

Defines logon password. 

User's library is private. 

Maximum library space is 500 units (500,000 
bytes). 

User can access project library 512. 

When user logs on, he is under control of VS APL. 
If a CONTENT attribute other than APL is 
defined, the user can access VS APL by issuing the 
ENTER command. 

Maximum workspace size is 100 units (100,000 
bytes). Default workspace size is 50 units (50,000 
bytes). VSPC permits a default workspace size that 
is smaller than that required by VS APL. To 
activate a VS APL workspace, a user should have a 
default workspace size of at least 20 units (20,000 
bytes). 

Maximum size of a single shared variable is 1000 
bytes. Maximum number of shared variables is 5. 

If the user intends to access VS APL workspaces in public or project libraries, 
the maximum workspace size must be at least as large as the maximum 
workspace size of those libraries. 

See also "Transferring Conversion Program Output to VSPC" for a 
discussion of how user profiles can be defined as a result of workspace 
conversion. 



SSMAX( 1000 5 ) 
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DEFINING AUXILIARY PROCESSORS 

This section describes how to define auxiliary processors to CMS and VSPC. 

Defining Auxiliary Processors to CMS 

Under CMS, auxiliary processors are not defined as such. An auxiliary 
processor exists as a CMS file whose filename is the name used to invoke it, 
whose filetype is TEXT, and whose filemode is any mode acceptable to CMS. 

Defining Auxiliary Processors to VSPC 

The internal auxiliary processors distributed with VS APL for use under 
VSPC are defined to VSPC during the installation procedure. They are 
identified as numbers 121 (APL VSPC file auxiliary processor), 122 
(EBCDIC VSPC file auxiliary processor), 123 (VSAM file auxiliary 
processor) and 124 (full screen management auxiliary processor). If you have 
obtained the source code for VS APL, you can change the numbers by 
performing these actions: 

1 . Modify VS APL module APLPCOAP by specifying the new numbers as 
operands of the APAPL, APBCD, APVSAM and APFSM keywords of the 
APLPCOAP marco. Assemble the module. 

2. Link-edit the VS APL load module as described in the installation 
procedure. 

3. Execute the VSPC Service Program with DEFINE AP control statements 
to define the new numbers to VSPC (see VSPC Installation Reference 
Material). 

4. Specify the new numbers for APAPL, APBCD, and APVSAM as the 
values of global variables APAP, APEP, and APVSAM in distributed 
workspace 2 VSFILES. 

5. Specify the new number for APFSM as the value of global variable 
APFSM in workspace 2 FULLSCREEN. 

To define a user-written auxiliary processor to VSPC, execute the VSPC 
Service Program with a DEFINE AP control statement as described in VSPC 
Installation Reference Material. 
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VS APL PUBLIC AND PROJECT LIBRARIES 



In this section, the procedures for creating and maintaining VS APL public 
and project libraries are described. 



VS APL Libraries under CMS 



Library Table File 



Under CMS, a VS APL public or project library is a collection of workspaces 
that has the properties described in the following sections. The libraries are 
defined in a CMS file called the library table file. When VS APL is installed, 
the library table file and public libraries 1 through 999 are created; no project 
libraries are created. 



The library table file defines public and project libraries to VS APL under 
CMS. The filename and filetype of the library table file are both APLIBTAB. 
The library table file distributed with VS APL defines libraries 1 through 999 
as public. When VS APL is installed, the file is placed on the Y-disk, but it 
can reside on any disk. It is located via the standard CMS search order. 

When VS APL is invoked, the library table file is read into virtual storage. 
When a VS APL user requests access to a public or project library, the 
executor searches the file sequentially from the beginning for the specified 
library number. The information from the first matching entry is used to 
identify the library type and, if a project library, to link dynamically to the 
project library disk. 

Records in the file are 80-byte card images of free format. Fields are 
delimited by one or more blanks. There are two types of records; each defines 
a single library or a range of libraries: 

PUBLIC libnuml ( f irst-libnum last-libnum ) 

PROJECT libnuml ( f irst-libnum last-libnum) owner device 

PUBLIC or PROJECT 

is the library type; only the first two letters are required. 

libnum 

is a library number; it can be any positive integer other than 1001 
(reserved for VS APL users' private libraries) and no greater than seven 
digits. 

( f irst-libnum last-libnum) 

is a range of library numbers; the first number must be less than or equal to 
the second number. 

owner 

is the VM/370 user identification of the owner of the disk on which the 
project library resides. 

device 

is the virtual device address, as defined in the owner's directory entry, of 
the disk on which the project library resides. 

Use the CMS editor to maintain the library table file (see IBM Virtual 
Machine Facility/ 370: EDIT Guide). 
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Public Libraries 



How to Create a Public Library 



For VS APL under CMS, a public library is a collection of workspaces that 
has these properties: 

• It resides on a disk that is accessed as the Y-disk. The disk can contain 
more than one public library. It must not contain project libraries. 

• It is defined as a public library in the library table file. For example, public 
libraries 1 through 999 are defined as: 

PUBLIC ( 1 999 ) 

• Each workspace in the library is a CMS file whose filetype is Wnnnnnnn, 
where nnnnnnn is the library number. For example, workspace 1 NEWS is 
a CMS file whose filename is NEWS and whose filetype is W0000001. 

• Any VS APL user can list, load, or copy workspaces in the library. 

• No VS APL user can save or drop workspaces in the library. The library is 
maintained with CMS commands. 



Public libraries 1 through 999 are defined in the distributed VS APL system. 
The disk that contains public libraries is defined during the installation 
procedure. 

To create a public library with a number greater than 999 or to change the 
distributed definition of public libraries, use the CMS editor to modify the 
library table file. 



How to Maintain a Public Library 



Public library workspaces can be added, replaced, or deleted only by someone 
who is allowed write access to the public library disk. The maintenance 
functions are performed with CMS commands. The functions should be 
performed when no one is using VS APL. If this is not possible, notify VS 
APL users that they are not to access the Y-disk until the maintenance 
functions are completed. 

To add or replace a public library workspace: 

1 . Have the VS APL user who created the workspace issue these CP and 
CMS commands to spool it to you: 

SPOOL PUNCH userid 

DISK DUMP filename filetype 

userid 

is your VM/370 user identification. 

filename filetype 

is the workspace identification. 

2. Access the public library disk in read/ write mode and any filemode (B is 
used in the following examples). 

3. Transfer the workspace from the virtual reader to the A-disk: 

DISK LOAD 
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Project Libraries 



How to Create a Project Library 



4. Copy the workspace from the A-disk to the public library disk and rename 
it. Note that the filetype of private workspaces is VSAPLWS. For example: 

COPYFILE NEWPUB VSAPLWS A = W0000003 B (REPLACE 

Specify the REPLACE option only if the workspace is intended to replace 
one with the same identification. 

To delete a public library workspace: 

1. Access the public library disk in read/write mode and any filemode. 

2. Erase the workspace. For example: 

ERASE NEWPUB W0000003 B 



For VS APL under CMS, a project library is a collection of workspaces that 
has these properties: 

• It resides on a disk that can be linked to dynamically as a G-disk with 
virtual device address 197. The disk can contain more than one project 
library. It must not contain public libraries. 

• It is defined as a project library in the library table file. For example, 
project library 2000 which is owned by CMS user ABC 1234 and resides 
on his disk at virtual device address 196 is defined as: 

PROJECT 2000 ABC1234 196 

• Each workspace in the library is a CMS file whose filetype is 'Wnnnnnnn, 
where nnnnnnn is the library number. For example, workspace 2000 
PROJWORK is a CMS file whose filename is PROJWORK and whose 
filetype is W0002000. 

• Any VS APL user who knows the read password defined for the disk can 
list, load, or copy workspaces in the library. 

• Any VS APL user who knows the write password defined for the disk can 
save or drop workspaces in the library. 



To create a project library, first decide whether it is to reside on an existing 
disk or on a new disk. It must reside on a new disk if maximum access control 
is wanted. VS APL users' access to project libraries is controlled by 
passwords associated with a disk, not with a library. 

To define the project library, use the CMS editor to add a record to the 
library table file. If the library is to reside on a new disk, define the disk as 
described in the following paragraphs; otherwise, creation of the library is 
completed. 
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The procedure for defining a disk (that is, for defining or modifying a 
VM/370 user directory entry) is described in IBM Virtual Machine 
Facility/ 3 70: Operator's Guide. When defining a project library disk, 
observe these guidelines: 

• Define the disk in a VM/370 user directory entry that is used for no 
purpose other than to contain the definition of the project library disk(s). 
This is recommended because VS APL links to project disks dynamically 
and cannot do so if a permanent link exists. If the disk is defined in an 
active VM/370 user directory entry, that user must detach the disk each 
time he logs on. 

• Define passwords as required to impose the desired level of control. A VS 
APL user must specify the read password for LIB, LOAD, and COPY 
commands; the write password for SAVE and DROP commands. To allow 
uncontrolled access, define a password as ALL. 

• Define sufficient space for anticipated workspace storage (see "Auxiliary 
Storage Requirements for Workspaces"). 

After the project library disk has been defined, format it using the CMS 
command FORMAT. 



How to Maintain a Project Library 



Project library workspaces can be added, replaced, or deleted by any user 
who knows the write password defined for the disk on which the project 
library resides. Maintenance is normally performed with VS APL commands 
SAVE and DROP; it can also be performed with CMS commands as 
described in "How to Maintain a Public Library." 



VS APL Libraries under VSPC 



Under VSPC, a VS APL public or project library is a VSPC public or project 
library that contains workspaces with a content attribute of APL. 

Use either the VSPC DEFINE command or the VSPC Service Program 
DEFINE control statement to create a public or project library (see VSPC 
Installation Reference Material). An example of DEFINE operands for a 
public library is: 

Operand Description 

USER( 3 ) Defines user number and library number 3. 

PASSWORD ( XYZ ) Defines password which must be specified to 

logon as user 3 or to gain access to the library; if 
access is not to be controlled, specify NOPASS. 

LIBTYPE( PUBLIC c ) Library is public; see discussion below of library 

maintenance for meaning of C. 

SPACE ( 1 000 ) Maximum library space is 1000 units (1,000,000 

bytes). 

CONTENT ( APL ) Defines the content attribute of the workspace 

attached when a user logs on as user number 3. 

INTPRMAX( 100 50 ) Maximum workspace size is 100 units (100,000 

bytes); default workspace size is 50 units (50,000 
bytes). 
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The maximum workspace size must be no greater than that of VS APL users 
who access workspaces in the library. 

To define a project library, specify operands as above except for the library 
type, which is PROJECT rather than PUBLIC. 

Public and project libraries are maintained by users who have the requisite 
access to the libraries. In terms of library access, there are three types of 
users: 

• The library manager is the user who has logged on to VSPC by supplying 
the library number. 

• The workspace owner is the user who stored the workspace in the library. 

• Other users are those other than the library manager or workspace owner 
who are allowed to access the library. All users are allowed to access public 
libraries. Only those users whose profile definition includes the PROJLIB 
operand are allowed to access the specified project library. 

For both public and project libraries, if C is specified in the LIBTYPE 
operand when the library is defined, only the library manager can store, 
replace, or delete a workspace. If C is not specified, only the workspace 
owner can replace a workspace; either the workspace owner or the library 
manager can delete a workspace; other users can store new workspaces and 
thus become workspace owners. 

To store a new workspace or replace an existing one, use the VS APL 
command SAVE. To delete a workspace, use the VS APL command DROP 
or the VSPC command PURGE. 
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WORKSPACE CONVERSION 



General Information 



This section describes how to convert APIA 360, APLSV, and APL/CMS 
workspaces to VS APL workspaces. Throughout this section, the term source 
APL is used to mean APIA 360, APLSV, or APL/CMS. 



This section contains information that is applicable to workspace conversion 
under both CMS and VSPC unless noted otherwise. 



Pre-Conversion Considerations 



Conversion Input 



Conversion Options 



There are three items — library numbers, workspace names, and 
passwords — that may be unacceptable to CMS or VSPC. These items can be 
modified during the conversion procedure, as described later. However, they 
should be modified by the owners of the source APL workspaces before the 
workspaces are dumped. Modifying these items before rather than during the 
conversion procedure ensures that they are modified as the workspace owners 
wish them to be and simplifies the conversion procedure. 

The unacceptable items are: 

• A library number greater than seven digits. 

• A workspace name that contains deltas, underscored letters, lowercase 
letters, or national characters. 

• For CMS only, a workspace name longer than eight characters. 

• For VSPC only, a password that contains deltas or underscored characters. 
An invalid logon password can be altered by a VSPC administrator 
following conversion. An invalid workspace password must be modified by 
the workspace owner prior to conversion; a workspace with an invalid 
password cannot be accessed, and there is no way to alter the password. 



Input to the conversion procedure is a workspace dump tape from the source 
APL system. The tape can be multi- volume. For APL \ 3 60 and APLSV, the 
tape is produced by the source APL utility program; it can be a full dump, an 
incremental dump, or a selective dump. For APL/CMS, the tape is produced 
by the CMS TAPE DUMP command; it must contain only workspaces that 
were created on Version 2 of APL/CMS. 



There are three options that define which of the input workspaces are to be 
processed: 

Option Description 

Full All workspaces on the input tape are processed. 

Resume All workspaces on the input tape, beginning with a specified workspace, 

are processed. 

Select Only the specified workspaces are processed. 
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Conversion Output 



There are two options that define the type of conversion for the selected 
workspaces: 

Option Description 

Format Workspace is converted to the format defined for VS APL. 

Content Includes format conversion. In addition, all function statements are 

examined for items that will not execute correctly under VS APL. Such 
items are converted to their VS APL equivalent, if there is one. The 
incompatible items, whether converted or not, are reported. 

These types of conversion are described in greater detail in VS APL for 
CMS: Terminal User's Guide and VS APL for VSPC: Terminal User's 
Guide. 



Output of the conversion procedure is workspaces that can be executed by VS 
APL and a conversion report. The converted workspaces may or may not 
execute properly, depending on their content. The conversion report is 
intended for distribution to the owners of the workspaces. It gives 
information about the converted workspaces and, if content conversion was 
done, information about items that must be evaluated or modified by the 
workspace owner to ensure proper execution. 

Conversion program error messages are listed in the "Messages" section. 

Workspace Conversion under CMS 

There are two workspace conversion programs that execute under CMS: 
APLCVCMS converts APIA 360 and APLSV workspaces for use under 
CMS; APLCVRPQ converts APL/ CMS workspaces for use under either 
CMS or VSPC. The procedures for using the two programs are described in 
this section and are the same unless noted otherwise. 

Auxiliary Storage Required by Conversion Programs 

When converting APL/ CMS workspaces for use under VSPC, a scratch tape 
and A-disk space are required. The APLCVRPQ conversion program 
transfers each converted workspace to the tape and creates two files of job 
control statements on the converter's A-disk. The tape and the punched JCL 
files are subsequently used with the VSPC Service Program as described in 
step 6 of the conversion procedure, below. The amount of A-disk space 
required is n 800-byte blocks, where n is the number of converted 
workspaces multiplied by 0.3. 

When converting APL/CMS workspaces for use under CMS, APL\360 
workspaces, or APLSV workspaces, only A-disk space is required. The 
APLCVRPQ and APLCVCMS conversion programs transform each input 
workspace to a CMS file on the converter's A-disk. Estimate the amount of 
disk space required according to the number of workspaces to be converted, 
their size, and the amount of data they contain (see "Auxiliary Storage 
Requirements for Workspaces"). If possible, use an A-disk with sufficient 
space for all the workspaces to be converted. This should be possible if the 
input tape is a single volume. 
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The simplest way to convert a multi-volume input tape is to segment the job 
by volume. Allocate the maximum disk space allowed by CMS (246 
cylinders) and do a separate full conversion of each volume as if it were a 
complete dump tape. Directory information, which may be present on the first 
volume of the input tape, is not needed for VS APL under CMS and is 
ignored by the conversion program. 

See the last item in step 5 of the conversion procedure for a discussion of how 
to resume conversion if it terminates abnormally because of insufficient disk 
space. 

Identification of Converted Workspaces 

When an APL \ 3 60 or APLSV workspace is converted, its identification is 
transformed to a CMS file identification. The workspace name, truncated 
from the right to eight characters, becomes the CMS filename. The library 
number, truncated from the left to seven digits or extended to the left with 
zeros to seven digits, and prefixed with a W, becomes the CMS filetype. The 
CMS filemode is always Al. For example: 

Workspace Identification CMS File Identification 

25 GEN WORK GENWORK W0000025 Al 

1234567 COMPUTATION COMPUTAT W1234567 Al 

1 2345678 XREF XREF W2345678 A 1 

When an APL/ CMS workspace is converted, its identification (which is a 
CMS file identification) is retained with no change. The filetype of a private 
APL/ CMS workspace is VMAPLWS. The filetype of a public APL/CMS 
workspace is Pnnnnnn, where nnnnnn is the library number. 

After workspaces have been converted, it may be necessary to change their 
identification. This can be done as part of the conversion procedure (as 
described in step 6) or by the recipients of the converted workspaces. The 
required changes are: 

• The filetype of private workspaces must be changed to VSAPLWS. 

• For APL/CMS workspaces only, the filetype of public libraries must be 
changed to Wnnnnnnn, where nnnnnnn is the library number. 

• For APL/CMS workspaces only, lowercase letters or national characters 
that occur in a filename must be changed to uppercase letters or numbers. 

Workspace Conversion Procedure 



1. Log on to VM/370 and IPL CMS with a virtual machine large enough to 
execute the conversion program (see "Virtual Storage Requirements"). 

2. Access an A-disk in read/ write mode with the required amount of disk 
space (see "Auxiliary Storage Required by Conversion Programs"). If the 
disk is newly allocated, format it using the CMS FORMAT command. 

3. Ask the system operator to mount the workspace dump tape and to attach 
the tape drive as virtual device 181. If converting APL/CMS workspaces 
for use under VSPC, also ask the system operator to mount a scratch tape 
and to attach the tape drive as virtual device 182. 
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4. Invoke the conversion program and specify the desired options by issuing 
one of the following CMS commands: 

• To invoke the APIA 360 and APLSV conversion program: 

APLCVCMS [FULL | RESUME | SELECT] [CONTENT I NOCONTENT] 

The meaning of the operands is described in "Conversion Options"; 
NOCONTENT selects the format option. The operands can be 
truncated down to their initial character. The sequence in which the two 
operands are entered is immaterial. The default operands are FULL and 
CONTENT. 

• To invoke the APL/CMS conversion program: 

APLCVRPQ [FULL | RESUME] [CONTENT I NOCONTENT] 

The operands are as described above. Note that the SELECT option is 
not supported. 

5. The conversion procedure is conversational. Enter information as 
explained below when prompted to do so. If the information is an APL 
workspace identification, represent APL characters with EBCDIC 
characters as follows: 



APL 


EBCDIC 


0-9 


0-9 


L~Zl 


a-z (lowercase) 


A-Z 


A-Z (uppercase) 


A 


* 


A 


$ 



Note that when the conversion program prints a workspace identification 
as part of a prompt, it uses A-Z to represent A-Z and a-z to represent 

ArJL 

• If the input option is RESUME, enter the identification of the 
workspace at which conversion is to begin as: 

library-number workspace-name 

• If the input option is SELECT, enter a list of the workspaces to be 
converted. The list can have up to 100 entries. Each entry can be one of 
the following: 

library-number workspace-name 
to select a specific workspace. 

1 ibrary-number 

to select all workspaces in a specific library. 

Press the RETURN key after each entry. Press the RETURN key alone 
to terminate the list. Entries in the list that are not found on the input 
tape are ignored. 

• If converting APL/CMS workspaces, enter YES or NO (depending on 
the destination of the converted workspaces) in response to this prompt: 

IS OUTPUT FOR VSPC ( YES I NO ) 



52 VS APL Installation Reference Material 



• If a CMS file identification duplicates that of a file already on the 
A-disk, enter one of the following options: 

Option Description 

RENAME Give the workspace a new name. In response to the 

next two prompts for filename and filetype, enter the 
desired CMS filename and filetype or press the 
RETURN key alone to leave either one unchanged. 
Filetype, if entered, must be as described earlier (W 
followed by seven digits). 

IGNORE Reject the workspace; do not convert it. 

REPLACE Replace the existing CMS file with this one. 

CANCEL Terminate execution of the conversion program. 

• If a workspace name is invalid (contains deltas or underscored letters), 
enter the RENAME, IGNORE, or CANCEL option as described in the 
preceding step. 

• When end of volume is reached, either enter CANCEL to terminate 
execution of the conversion program, or do the following to continue 
with the next volume: 

- Enter CP mode by pressing the ATTN key twice, (or press the PA1 
key if an IBM 3270 terminal is being used). 

- Use the CP command MSG to ask the system operator to mount the 
next volume on the tape drive attached as virtual device 181. 

- Type the CP command BEGIN. 

- Type RESTART. 

• If the conversion program terminates abnormally because the A-disk is 
full or because of an unrecoverable error, the last partially converted 
workspace is erased from the A-disk and its identification is printed at 
the terminal. Process the workspaces that have been converted by doing 
step 6 of the conversion procedure. Then rewind the input tape by 
issuing this CMS command: 

TAPE REW 

and resume the conversion procedure at step 4. Specify the RESUME 
option and the identification of the workspace that was printed when 
the conversion program terminated. 

6. When the conversion program has completed execution, process the 
converted workspaces according to their destination: 

• If the converted workspaces are to be used with VS APL under CMS 
and are not owned by the converter, separate the conversion report into 
sections by library number and distribute the sections to their owners. 
Disperse the converted workspaces to their owners and erase them from 
the A-disk by doing one of the following: 

- To change the filetype of APL \ 3 60 or APLSV private workspaces to 
VSAPLWS before dispersing them, use the CMS editor to create a 
file named NEWTYPE EXEC containing these statements: 

SCONTROL ERROR 

RENAME SI S2 S3 = VSAPLWS = 



Workspace Conversion 53 



Then issue these CP and CMS commands for each owner: 

SPOOL PUNCH userid 

LISTFILE * filetype A (EXEC 

CMS NEWTYPE 

LISTFILE * VSAPLWS A (EXEC 

CMS DISK DUMP 

CMS ERASE 

userid 

is the owner's VM/370 user identification. 

filetype 

is that of the owner's workspaces in the form Wnnnnnnn; it can be 
obtained from the conversion report. 

- To disperse APIA 360 or APLSV workspaces without changing their 
filetype, issue these CP and CMS commands for each owner: 

SPOOL PUNCH userid 
LISTFILE * filetype A (EXEC 
CMS DISK DUMP 
CMS ERASE 

The operands are as described above. 

- To disperse APL/CMS workspaces, issue these CP and CMS 
commands for each workspace: 

SPOOL PUNCH userid 

DISK DUMP filename filetype 

ERASE filename filetype 

userid 

is the owner's VM/370 user identification. 

filename filetype 

is the identification of the APL/CMS workspace. 

• If the converted workspaces are to be used with VS APL under CMS 
and are owned by the converter, the conversion procedure is completed 
except for changing the filetype. 

To change the filetype of all private workspaces, issue this CMS 
command: 

RENAME * filetype A = VSAPLWS = 

filetype 

is either that generated for APL \ 3 60 and APLSV workspaces in the 
form Wnnnnnnn, where nnnnnnn is the source APL library number; 
or VMAPLWS for APL/CMS workspaces. 

To change the filetype of APL/CMS public workspaces, issue this CMS 
command: 

RENAME * Pnnnnnn A = Wnnnnnnn = 

nnnnnn 

is the APL/CMS library number; note that the new filetype has an 
additional zero to the left. 
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If the converted workspaces are APL/CMS workspaces to be used 
under VSPC, use the output of the conversion program as input to the 
IMPORT function of the VSPC Service Program. 

There are two JCL files on the A-disk. The file named IMPORT 
DDCARDS contains the DD statement shown below for each converted 
workspace. The file named IMPORT COMMANDS contains the 
IMPORT statement shown below for each converted workspace. 

//ddname DD DSN=wsname , UNIT=2400 , LABEL=( n , NL) , 

// VOL=SER=XXXX,DISP=( OLD, PASS ) , 

// DCB=( LRECL=80 , BLKSIZE=800 , RECFM=FBS ) 

IMPORT wsname FROM ( ddname ) TYPE( OBJECT) CONTENT ( APL) 

ddname 

is M1 through Mn, where n is the number of converted workspaces. 

wsname 

is the workspace name (the CMS filename). 

n 

is the position of the workspace on the output tape. 

The JCL files must be modified before they are used to run the VSPC 
Service Program. Use the CMS editor to modify them before printing 
and punching them, or modify them manually afterward. The required 
modifications are: 

- Add the JCL statements required by the service program. 

- Add an AUTH control statement. 

- In each DD statement, change XXXX to the serial number of the 
output tape. 

- If the output tape has standard labels, change the LABEL 
subparameter NL in each DD statement to SL. 

- If lowercase letters or national characters occur in a workspace name, 
change them to uppercase letters or numbers in the DD and IMPORT 
statements. 

- If the workspaces are to be transferred to VSPC libraries other than 
that specified in the AUTH control statement, insert the library 
number in each IMPORT statement preceding wsname. 

- If the VSPC host system is DOS/VS, use the information in file 
IMPORT DDCARDS to prepare the required TLBL statements. 

Print and punch the files by issuing these CMS commands: 

PRINT IMPORT DDCARDS 

PRINT IMPORT COMMANDS 

PUNCH IMPORT DDCARDS 

PUNCH IMPORT COMMANDS 

Send the output tape, the conversion report, and the printed and 
punched JCL files to the VSPC installation. 

At the VSPC installation, execute the VSPC Service Program to transfer 
the converted workspaces to VSPC libraries. IMPORT, AUTH, and the 
VSPC Service Program are described in VSPC Installation Reference 
Material. 



Workspace Conversion 55 



Workspace Conversion under VSPC 



There is one workspace conversion program that executes under OS/VS 
(APLCVOS) and another that executes under DOS/VS (APLCVDOS). Both 
programs convert APIA 360 and APLSV workspaces. The procedures for 
using the two programs are described in this section and are the same unless 
noted otherwise. The procedure for converting APL/CMS workspaces for use 
under VSPC is described in "Workspace Conversion under CMS." 

Converting workspaces to be used under VSPC is basically a three-step 
procedure: 

1. Execute the conversion program. The output is a conversion report and a 
data set which contains the converted workspaces and user profiles. 

2. Separate the conversion report into sections by library number and 
distribute the sections to their owners. 

3. Execute the VSPC Service Program with COPY control statements to 
transfer the converted workspaces to VSPC libraries and (optionally) to 
define their owners to VSPC. Input to the VSPC Service Program is the 
data set output by the conversion program. 

If the source APL dump tape contains library numbers or workspace names 
that are unacceptable to VSPC, the procedure must be executed twice. First 
do a full conversion. The unacceptable workspaces are rejected by the 
conversion program but identified on the conversion report. Then do a 
selective conversion of the rejected workspaces using information provided by 
the workspace owners to rename them. 



Conversion Control Statements 



Input to the conversion program is an APL \ 360 or APLSV workspace dump 
tape and a set of control statements as described below. All control 
statements are optional. A statement can appear anywhere within columns 1 
to 71 of a card; columns 72 to 80 are ignored; continuation is not allowed. 
The operands shown in uppercase can be truncated down to their initial 
character. Operands can be separated by blanks or parentheses. If an operand 
is an APL workspace identification, represent APL characters with EBCDIC 
characters as follows: 



APL 


EBCDIC 


0-9 


0-9 


A-Z 


A-Z (uppercase) 


A~z 


a-z (lowercase) 


A 


.* 



FORMAT Statement 



Use the FORMAT statement to select format conversion. Omit the statement 
to select content conversion. The syntax of the statement, which has no 
operands, is: 

FORMAT 
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SELECT Statement 



RESUME Statement 



DESCRIBE Statement 



Use the SELECT statement to identify the libraries and/or workspaces to be 
converted during a selective conversion, and (optionally) to provide new 
identifications for workspaces with invalid library numbers or names. The 
maximum number of SELECT statements allowed is 100. If SELECT 
statements are included, RESUME is not allowed. For full conversion, omit 
both SELECT and RESUME statements. 

The syntax of the statement is: 

SELECT libnum [newlibnum] [wsname [newwsname] ] 

libnum 

is the library number of the source APL workspace. 

newlibnum 

is the VSPC library number; if omitted, the library number is 1 ibnum. The 
number cannot exceed seven digits. 

wsname 

is the name of the source APL workspace; if omitted, all workspaces in the 
specified library are selected. 

newwsname 

is the name of the workspace in VSPC; if omitted, the name is wsname. 
The name cannot exceed 1 1 characters and cannot contain deltas or 
underscored letters. 



Use the RESUME statement to identify the workspace at which conversion is 
to resume. If RESUME is used, SELECT statements are not allowed. For full 
conversion, omit both RESUME and SELECT statements. 

The syntax of the statement is: 

RESUME libnum wsname 

libnum 

is the library number of the source APL workspace. 

wsname 

is the name of the source APL workspace. 



Use the DESCRIBE statement to supply library space and shared variable 
space values. Only one DESCRIBE statement is allowed. The values apply to 
all libraries processed by the conversion program. 

The syntax of the statement is: 

DESCRIBE [LSPACE n] [SHARE m] 

LSPACE n 

is the maximum size of a library; n is units of 1000 bytes. 

SHARE m 

is the maximum size of a shared variable; m is units of 1000 bytes. 
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The conversion program determines library space for each user as follows: 

• If the input tape contains directories, the LSPACE operand of the 
DESCRIBE statement is ignored. The conversion program computes 
LSPACE according to the user's source APL workspace size (WSSIZE) 
and quota (WSQUOTA) as follows: 

X+20480r6144+l .lxWSSIZE 

Greater of 20K and source WS size plus 10% plus 6144 for internal 
buffers 

X«-2048xlp0 2048T2047+X 
Rounded to nearest 2K 

VSPCSIZE+lpO 1000T999+Z 

Rounded to nearest 1000 and converted to units of 1000 

LSPACE+VSPCSIZExWSQUOTA 
Multiplied by workspace quota 

• If the input tape has no directories, LSPACE is as specified in the 
DESCRIBE statement. There are no directories if the input tape is a 
selective dump, or if it is multi-volume and the first volume is not input to 
the conversion program. 

• If there is no DESCRIBE statement, or if LSPACE is not specified, 
LSPACE is 500 units. 

The conversion program specifies each user's maximum shared variable size 
to be either that specified in the DESCRIBE statement or 0. It is the specified 
SHARE value if the input tape contains directories, the user's directory 
indicates a shared variable quota other than 0, and a SHARE value is 
specified in the DESCRIBE statement. In all other cases, SHARE is 0. For 
APL\360, which does not support shared variables, the SHARE value 
resulting from conversion is always 0. 

Note that APLSV defines the number of shared variables that a user can 
have, but does not restrict the size of a shared variable. Therefore, if a 
SHARE value is not defined to the conversion program and not otherwise 
defined to VSPC, or if the SHARE value is inadequate, a user who migrates 
to VS APL from APLSV will not be able to execute functions that use shared 
variables. 
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OS/VS Workspace Conversion Program 



Execution of job CONVERT from the sample OS/VS JCL distributed with 
VS APL can be used to run the OS/VS conversion program. Alter the job to 
suit your requirements as noted below. 

REGION=value 1 

PGM=APLCVOS 

DSN=VSAPL . CNVTLIB , DISP=SHR 

DSN=dsname , VOL=( PRIVATE , , SER=volser ) , 

UNIT=2400 , DISP=OLD , LABEL=( 1 , BLP )2 

DSN=dsname , VOL=( PRIVATE , , SER=volser ) , 

UNIT=2400 , DISP=OLD , LABEL=( 2 , BLP )2 

DSN=dsname , VOL=( PRIVATE , , SER=volser ) , 

UNIT=2400 , DISP=OLD , LABEL=( 3 , BLP )2 

UNIT=SYSDA,SPACE=( 8004, ( 5,5 ) ,RLSE )3 

DSN=APLOUT , VOL=SER=volser , UNIT=2400 , 

DISP=( NEW, KEEP , KEEP ) , LABEL=( , SL ) 4 

SYSOUT=A, DCB=BLKSIZE= 1 2 1 

SYSOUT=A 

* 

Insert conversion control statements 5 . 

/* 

1 For region size, see "Virtual Storage Requirements." Supply other JOB parameters according to your 
requirements. 

2 The APLTLBL, APLTDTA, and APLTEOV DD statements describe the source APL dump tape. The 
conversion program bypasses label processing. Supply the information shown in lowercase. 

■> The APLDIRE DD statement describes a temporary data set used by the conversion program for directory 
entries (information about each input account number). Each 8004-byte block has space for 400 entries. 
The space allocation in the sample JCL allows for conversion of 32,000 account numbers. Modify the space 
allocation, if necessary. 

4 The APLOUT DD statement describes the sequential data set created by the conversion program. It can be 
tape, as described in the sample JCL, or disk. Supply the information shown in lowercase. If output to disk 
is wanted, supply the appropriate information. 

' Insert conversion control statements after the SYSIN DD statement. 



//CONVERT 


JOB 


// 


EXEC 


//STEPLIB 


DD 


//APLTLBL 


DD 


// 




//APLTDTA 


DD 


// 




//APLTEOV 


DD 


// 




//APLDIRE 


DD 


//APLOUT 


DD 


// 




//APLRPRT 


DD 


//SYSUDUMP 


DD 


//SYSIN 


DD 
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DOS/VS Workspace Conversion Program 



Execution of job CONVERT from the sample DOS/VS JCL distributed with 
VS APL can be used to run the DOS/VS conversion program. Alter the job 
to suit your requirements as noted below. 

// JOB CONVERT 

// ASSGN SYS004,TAPEi 

// ASSGN SY005,TAPE,VOL=CNVRT 2 

// ASSGN SYS006,3330 / VOL=volserial,SHR3 

// DLBL APLDIRE, 'file-id* , , SD 

// EXTENT SYS006,volserial, 1 , sequence, rel-track, .. . 

. . . number-of -tracks 
// EXEC APLCVDOS,SIZE=size 4 
Insert conversion control statement 5 . 
/* 
/ g 

1 The SYS004 assignment describes the source APL dump tape. The conversion program does not perform 
DOS label processing, but reads the label as the first file. 

2 The SYS005 assignment describes the output tape created by the conversion. No label or leading tape mark 
is written. 

•* The SYS006 assignment describes a temporary data set used by the conversion program for directory 
entires. This data set must reside on a 3330 DASD device. 

4 For partition size, see "Virtual Storage Requirements." 

5 Insert conversion control statements after the EXEC statement. 



User Profiles Created by Conversion Program 



The data set created by the conversion program contains a user profile for 
each converted library as well as the converted workspaces. The contents of 
each user profile created by the conversion program are: 

Item Value 

USER Source APL library number or new library number specified 

in SELECT statement. 

PASSWORD Source APL logon password if directories were processed by 
conversion program; otherwise NOP ASS. 

LIBTYPE Public library if USER is less than 1000; users other than the 

library manager can store files in the library (C is not 
specified). Private library if USER is greater than or equal to 
1000. 

SPACE Library space quota as determined by conversion program. 

See discussion of LSPACE in "DESCRIBE Statement." 

CONTENT APL 

SIZE edit-size (maximum size for editable data) is 0. 

obj-size (maximum size for object programs) is 0. 
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Item Value 

INTPRMAX maximum (maximum interpreter workspace size) is: 

J«-20480r6144 + l.lx WSSIZE 

Greater of 20K and source WS size plus 10% plus 
6144 for internal buffers 

J+X+8192 
Plus 8K 

X«-2048xlp0 2048T2047 + * 
Rounded to nearest 2K 

MAXIMUM+lpO 1000T999+J 

Rounded to nearest 1000 and converted to units of 
1000 

default (default interpreter workspace size) is VSPCSIZE 
(see "DESCRIBE Statement"). 

SSMAX size (maximum size of a shared variable) is as determined by 

conversion program. See discussion of SHARE in 
"DESCRIBE Statement." 

number (maximum number of shared variables) is source 
APL shared variable quota if directories were processed by 
conversion program; otherwise 0. Always for converted 
APL \ 360 workspaces. 

PROJLIB None 

JECODE None 

NOADM User not authorized to use VSPC administrator commands. 



Transferring Conversion Program Output to VSPC 



When a converted workspace is transferred to VSPC, it becomes a file in the 
VSPC library. Its library number is the source APL library number or the new 
library number specified in a SELECT statement. Its name is the source APL 
workspace name or the new workspace name specified in a SELECT 
statement. Its password is the source APL workspace password. 

Use the COPY control statement of the VSPC Service Program to transfer 
the conversion program output (converted workspaces and user profiles) to 
the VSPC library. Each user profile that does not exist in the VSPC library is 
inserted. If a user profile does exist in the library, the profile created by the 
conversion program is ignored. The converted workspaces are added to the 
newly defined or existing user libraries. 

If the owner of converted workspaces is a new VSPC user and if the profile 
created by the conversion program is not satisfactory, either ( 1 ) use DEFINE 
to create a user profile before transferring the conversion program output; or 
(2) use ALTER to modify the user profile after transferring the conversion 
program output. 

COPY, DEFINE, ALTER, and the VSPC Service Program are described in 
VSPC Installation Reference Material. 
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TRANSPORTING WORKSPACES BETWEEN CMS 
ANDVSPC 



When transporting VS APL workspaces between CMS and VSPC, no 
conversion is required. VS APL workspaces have the same format under all 
host systems. 



Transporting Workspaces from CMS to VSPC 

1. At the CMS installation: 



a. Ask the system operator to mount a scratch tape and to attach the tape 
drive as virtual device 181, 182, 183, or 184. 

b. Access the disk(s) from which the workspaces are to be transferred in 
read/only mode. 

c. Define the output device by issuing the CMS command: 

FILEDEF OUTMOVE TAPn ( RECFM F LRECL 800 BLOCK 800 

TAPn 

is the magnetic tape device where n can be 1, 2, 3, or 4 to represent 
device 181, 182, 183, or 184 respectively. 

d. Transfer the workspaces to tape by issuing these CMS commands for 
each workspace: 

FILEDEF INMOVE DISK filename filetype filemode 
MOVEFILE 

filename filetype filemode 

is the CMS identification of the workspace. 

e. When all workspaces have been transferred to tape, rewind and unload 
the tape: 

TAPE RUN TAPn 

2. At the VSPC installation, execute the VSPC Service Program with 
IMPORT control statements, using the tape as input, to transfer the 
workspaces to VSPC libraries. Each workspace on the tape is a separate 
data set. For OS/VS (VSPC), use one DD statement and one IMPORT 
control statement for each workspace. For DOS/VS (VSPC), use one 
IMPORT control statement for each workspace and one ENVIRONMENT 
control statement for the entire job. Although the input data sets contain 
800-byte unblocked records, they must be described as 80-byte blocked 
records to the service program. For example, to transfer the first two 
workspaces on the tape into OS/VS (VSPC) library 1002 and give them 
the names MYWS and TESTWS, use these statements: 



//MYWS 

// 

// 

//TESTWS 

// 
// 



DD 



DD 



DSN=MYWS , VOL=SER=volser , UNIT=2400 , 
DISP=( OLD, PASS ),LABEL=( 1 ,NL), 
DCB=(LRECL=80,BLKSIZE=800,RECFM=FBS) 
DSN=TESTWS , VOL=SER=volser , UNIT=2400 , 
DISP=( OLD, PASS ),LABEL=( 2,NL), 
DCB=( LRECL=80 , BLKSIZE=800 , RECFM=FBS ) 



IMPORT 1002 MYWS TYPE( OBJECT ) CONTENT(APL) 
IMPORT 1002 TESTWS TYPE(.OBJECT ) CONTENT( APL ) 
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To Perform the same operation for DOS/VS (VSPC), use these 
statements: 

//ASSGN SYS004,TAPE 

ENVIRONMENT DEVICE( 2400 004 NOREWIND ) NOLABEL - 

FORMAT( F ) BLOCKSIZE( 800 ) RECORDSIZEf 80 ) 

IMPORT 1002 MYWS TYPE ( OBJECT ) CONTENT ( APL ) 
IMPORT 1002 TESTWS TYPE( OBJECT) CONTENT ( APL ) 

See VSPC Installation Reference Material for a description of the 
VSPC Service Program and the ENVIRONMENT and IMPORT control 
statements. 



Transporting Workspaces from VSPC to CMS 



1. At the VSPC installation, execute the VSPC Service Program with 
EXPORT control statements to transfer the workspaces to tape. Transfer 
each workspace as an unlabeled data set containing 800-byte unblocked 
records. For OS/VS (VSPC), use one DD statement and one EXPORT 
control statement for each workspace. For DOS/VS (VSPC), use one 
EXPORT control statement for each workspace and one 
ENVIRONMENT control statement for the job. For example, to transfer 
two workspaces named MYWS and TESTWS from OS/VS (VSPC) library 
1002 as the first two data sets on the tape, use these statements: 



//MYWS 

// 

// 

//TESTWS 

// 
// 



DD 



DD 



DSN=MYWS , VOL=SER=volser , UNIT=2400 

DISP=( OLD, PASS ),LABEL=( 1,NL), 

DCB=( LRECL=80 , BLKSIZE=800 , RECFM=FBS ) 

DSN=TESTWS , VOL=SER=volser , UNIT=2400 , 

DISP=( OLD, PASS ) / LABEL=( 2,NL), 

DCB=( LRECL=80 , BLKSIZE=800 , RECFM=FBS ) 



EXPORT 1002 MYWS TYPE ( OBJECT ) CONTENT ( APL ) 
EXPORT 1002 TESTWS TYPE ( OBJECT ) CONTENT ( APL ) 

To perform the same operation for DOS/VS (VSPC), use these statements: 

//ASSGN SYS004,TAPE 

ENVIRONMENT DEVICE( 2400 004 NOREWIND) NOLABEL - 
FORMAT( F ) BLOCKSIZE( 800 ) RECORDSIZE( 80 ) 

EXPORT 1002 MYWS 
EXPORT 1002 TESTWS 

See VSPC Installation Reference Material for a description of the VSPC 
Service Program and the ENVIRONMENT and EXPORT control 
statements. 

2. At the CMS installation: 

a. Ask the system operator to mount the tape and to attach the tape drive 
as virtual device 181, 182, 183, or 184. 

b. Access the disk(s) to which the workspaces are to be transferred in 
read/write mode. 
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c. Define the input device by issuing this CMS command: 

FILEDEF INMOVE TAPn ( RECFM F LRECL 800 BLOCK 800 

TAPn 

is the magnetic tape device where n can be 1, 2, 3, or 4 to represent 
device 181, 182, 183, or 184 respectively. 

d. Transfer the workspaces from tape to disk by issuing these CMS 
commands for each workspace: 

FILEDEF OUTMOVE DISK filename filetype filemode 
MOVEFILE 

filename 

is the name of the workspace. 

filetype 

is VSAPLWS if the workspace is transferred to a private library; it is 
Wnnnnnnn if the workspace is transferred to a public or project 
library, where nnnnnnn is the library number. 

filemode 

is that of the disk to which the workspace is transferred. 
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USING THE VS APL MICROCODE ASSIST 



The VS APL microcode assist, which is available for System/370 Models 135 
and 145, performs some of the functions of the VS APL interpreter. The 
procedure for loading the microcode assist is described in Operator's Library: 
System/ 3 70 Model 135 Procedures and IBM System/ 3 70 Model 145 
Operator Procedures. If the microcode assist is there when VS APL is 
invoked, it is detected and used. 
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STORAGE REQUIREMENTS 



Virtual Storage Requirements 



Figure 3 shows the minimum virtual machine size (VM/370), region size 
| (OS/VS), and partition size (DOS/VS) required to install and execute VS 
APL and to execute the workspace conversion programs. 



Host 


To Install 


To Execute 


To Execute 


System 


VSAPL 


VSAPL 


Conversion Program 


VM/370 (CMS) 


400K 


400K.1 


200K + 3.1 x WS5 for APLCVCMS 


(APL non-shared) 






200K + 2. 1 x WS6 for APLCVRPQ 


VM/370 (CMS) 


SSA2 + 400K 


320K3 


as above 


(APL shared) 








OS/VS (VSPC) 


256K 


185K.4 


124K + 3.1 x WS5 


DOS/VS (VSPC) 


256K 


185K.4 


124K + 3.U WS5 



* Assumes a minimum-size workspace (20K) and no auxiliary processors. To execute with all distributed 
auxiliary processors and 4K of shared memory, add 20K. For additional shared memory or larger 
workspace, increase virtual machine size correspondingly. Users who access a large number of disks and 
files may require additional storage for CMS control blocks. 

^ Where SSA is the shared system's load address. 

3 This is the minimum-size CMS virtual machine. It allows a 100K workspace. You can increase the size of 
the virtual machine as noted in 1 above, but must not exceed the load address of the shared system. In 
addition, 192K (3 segments) of shared main storage is required. 

4 This is the virtual storage required for the VS APL interpreter and executor (including the internal 
auxiliary processors), rather than the region or partition size. It does not include virtual storage required for 
VSPC, access methods, and workspaces. 

5 Where WS is the size of each source APL workspace. 

° Where WS is the size of the largest source APL workspace; virtual machine size must be at least 264K. 
Figure 3. Virtual Storage Requirements for VS APL 



Auxiliary Storage Requirements 



In this section, direct access storage devices are identified as follows: 
2314: IBM 2314 Direct Access Storage Facility and IBM 2319 Disk Storage. 
3330: IBM 3330 Disk Storage and IBM 3333 Disk Storage and Control. 
3340: IBM 3340 Direct Access Storage Facility. 



Auxiliary Storage Requirements for VS APL 



Figure 4 shows the minimum auxiliary storage required to install VS APL as a 
non-shared system under CMS. Note the columns that indicate whether the 
storage requirement applies to the A-disk, the Y-disk, or both. The total 
cylinder requirements for each disk are computed using the total block 
requirements; they are not the sum of the cylinders required for each 
component. 

Figure 5 shows a summary of the minimum auxiliary storage required to 
install VS APL as a shared system under CMS. The detail is as shown in 
Figure 4, except that component APL MODULE requires 8 blocks and there 
is an additional component, APLMAIN MODULE, that requires 232 blocks 
on the A-disk. 
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Component 


Disk 
A Y 


800-byte 
Blocks 


Cylinders 
2314 3330 3340 


TEXT files for executor, 
interpreter, shared storage 
manager 


X 




814 


6 


4 


9 


TEXT files for conversion 
programs 


X 




256 


2 


1 


3 


Link-edit maps 


X 




136 






2 


Macros 


X 




125 






2 


APLINSTL EXEC 


X 




45 






1 


APL MODULE 


X 


X 


285 




2 


3 


APLCVCMS MODULE 


X 


X 


86 






1 


APLCVRPQ MODULE 


X 


X 


81 






1 


APL EXEC 


X 


X 


2 






1 


APLCVCMS EXEC 


X 


X 


2 






1 


APLCVRPQ EXEC 


X 


X 


1 






1 


Auxiliary processors 


X 


X 


60 






1 


APLMAC MACLIB 


X 


X 


119 






2 


Library table file 


X 


X 


1 






1 


Distributed workspaces 




X 


396 




2 


5 


Total for A-disk 


X 




2013 


14 


8 


21 


Total for Y-disk 




X 


1033 


7 


4 


11 



Figure 4. Auxiliary Storage Requirements for Non-Shared VS APL under CMS 











Cylinders 




Storage Device 


Unit of Storage 


Units Required 


2314 


3330 


3340 


A-disk 


800-byte block 


2013 


14 


8 


21 


Y-disk 


800-byte block 


801 


8 


4 


9 


CP volume 


4K page 


49 


2 


1 


3 



Figure 5. Auxiliary Storage Requirements for Shared VS APL under CMS 

Figure 6 shows the minimum auxiliary storage required to install VS APL 
under OS/VS (VSPC). The VSPC library storage requirement is for the 
distributed workspaces. 

Figure 7 shows the minimum auxiliary storage required to install VS APL 
under DOS/VS(VSPC). The VSPC library storage requirement is for the 
distributed workspaces. 



Auxiliary Storage Requirements for Workspaces 



The amount of auxiliary storage required for a workspace depends on the 
amount of data it contains, not on the size of the workspace. To compute the 
number of bytes required to store a workspace, subtract the space available, 
UWA, from the workspace size, ) WSSIZE. 

Under VSPC, a VS APL workspace is a VSPC file. VSPC files are stored in 
units of 1000 bytes. 
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Number of 










Directory 


Unit of 


Units 


Data Set 


Data Set Type 


Blocks 


Storage 


Required 


SYS1.LINKLIB 


partitioned 


1 


cylinder 1 


1 


(0S/VS1 only) 










SYS1.LPALIB 


partitioned 


1 


cylinder 1 


1 


(OS/VS2 only) 










VSAPL.OBJLIB 


partitioned 


20 


3200-byte 
block 


143 


VSAPL.CNVTLIB 


partitioned 


1 


cylinder 1 


1 


VSPC library 


VSAM 


— 


1000-byte 
unit 


500 



1 Storage requirements for load module data sets are for a 3330. 

Figure 6. Auxiliary Storage Requirements for VS APL under OS/VS (VSPC) 





Library or Disk File 


Directory 
Tracks 


Unit of 
Storage 


Units Required 
2314/2319 


3340 3330 


Relocatable library 


1 


cylinder 


8 


12 6 


Core-Image library 


2 


cylinder 


3 


4 2 


Deblocked object 
deck file 


- 


tracks 


100 


80 57 


VSPC library 
(VSAM) 


- 


1000-bytes 


500 


500 500 


Figure 7. Auxiliary Storage Requirements for VS APL under DOS/VS (VSPC) 



Under CMS, a VS APL workspace is a CMS file with a block size of 800 
bytes. Figure 8 shows the capacity per cylinder of the direct access storage 
devices supported by CMS in terms of 800-byte blocks and several data sizes. 









15K 


25K 


50K 


Device 


Blocks 


Clear WS 


Data 


Data 


Data 


2314 


150 


25 


7.5 


, 4.5 


2.3 


3330 


266 


44.3 


13.3 


8.1 


4.1 


3340 


96 


16 


4.8 


2.9 


1.5 



Figure 8. Auxiliary Storage Capacity per Cylinder 
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MESSAGES 
Messages under CMS 



Messages under VSPC 



Error and diagnostic messages that are issued by the CMS executor of VS 
APL are printed at the user's terminal. They are identified by a message 
number prefix of APL. They are documented in VS APL for CMS: 
Terminal User's Guide. 

A VS APL user can also receive messages issued by CP or CMS. CP and 
CMS messages are identified by message number prefixes of DMK and DMS, 
respectively. They are documented in IBM Virtual Machine Facility/ 3 70: 
System Messages. 



The following error and diagnostic messages are issued by the VSPC executor 
of VS APL and are printed on the VSPC online log. The VS APL user 
receives the message SYSTEM ERROR nnn, where nnn is the online log 
message number. 

APLP001I PGM CHECK LOOP IN APL PROCESSOR. 

Explanation: During processing of a program check, a second program check 
occurred. 

System Action: Message APLP011I, which shows the PSW and general 
registers at the time of the second program check, is issued. A dump is taken, 
and execution is terminated. 

User Action: Report the problem to the system programmer. 

APLP002I PGM CHECK IN EXECUTOR. 

Explanation: A program check occurred in the VS APL executor. 

System Action: Message APLP01 II, which shows the PSW and general 
registers at the time of the program check, is issued. A dump is taken, and 
execution is terminated. 

User Action: Report the problem to the system programmer. 

APLP003I EXECUTOR SAVE AREA BLOCK FULL. 

Explanation: The executor is designed so that routine calls are nested to a 
maximum depth of five. An attempt to call a sixth-level routine was made, 
and there is no sixth save area. 

System Action: A dump is taken, and execution is terminated. 

User Action: Report the problem to the system programmer. 

APLP004I INVALID ASSIST CHECK CONDITION CODE. 

Explanation: During initialization, when a test was made for the presence of 
the VS APL microcode assist, an unexpected condition code was returned. 

System Action: Execution continues without use of the VS APL microcode 
assist. 

User Action: Report the problem to the system programmer. 
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APLP005I UNEXPECTED SYSTEM ERROR CODE RECEIVED. 
RET: xxx, REAS: yyy, SYS: www, APL: zzzzz. 

Explanation: An unexpected error code was received from VSPC following a 
service request, xxx is the return code, yyy is the reason code, www is the 
VSPC request code, zzzzz is the VS APL service request code. 

System Action: A dump is taken. A clear workspace is loaded. Execution 
continues. 

User Action: Report the problem to the system programmer. 

APLP006I NO SYSTEM INDICATOR ON ASYNCH ENTRY. 

Explanation: VSPC invoked the VS APL processor for an asynchronous 
occurrence. No indicator was set to distinguish the cause. 

System Action: A dump is taken. Execution continues. 

User Action: Report the problem to the system programmer. 

APLP007I MULTIPLE UNEXPECTED ERROR CODES FROM 
SYSTEM. 

Explanation: Multiple unexpected error codes were received from VSPC 
following similar service requests. 

System Action: A dump is taken, and execution is terminated. 

User Action: Report the problem to the system programmer. 

APLP008I APL ASSIST INCOMPATIBLE WITH APL PROCESSOR. 

Explanation: During initialization, when a test was made for the presence of 
the VS APL microcode assist, it was discovered that the microcode assist is 
not at the same level as the VS APL processor. 

System Action: Execution continues without use of the VS APL microcode 
assist. 

User Action: Report the problem to the system programmer. 

APLP009I INSUFFICIENT STORAGE FOR MINIMUM WS. 

Explanation: The default workspace size defined in the user's profile is too 
small for VS APL operation. 

System Action: A dump is taken, and execution is terminated. 

User Action: Report the problem to the account administrator. 

APLP011I PSW: xxxxxxxx xxxxxxxx, REGS: 

Explanation: VS APL has been terminated because of a program check. This 
message shows the contents of the program check old PSW and the general 
registers. It is issued following messages APLP001I or APLP002I. 

System Action: Abend processing continues. 

User Action: Include this information when reporting the problem to the 
system programmer. 



74 VS APL Installation Reference Material 



APLP014I UNEXPECTED ERROR IN APL INTERNAL AP. 

Explanation: An unexpected error code was received from VSPC following a 
service request in an internal auxiliary processor. The prior message, 
APLP005I, gives additional information about the error. 

System Action: A dump is taken, and execution is terminated. 

User Action: Report the problem to the system programmer. 



Conversion Program Messages 



The following error messages are issued by workspace conversion programs 
and appear on the conversion report. With the conversion programs that run 
under CMS, the messages are also printed at the terminal. When a workspace 
or library is in error, its identification either appears in the message or 
preceding the message in the conversion report. 

There are messages in addition to those listed below that appear on the 
conversion report. They are directed to the workspace owner and are 
documented in VS APL for CMS: Terminal User's Guide and VS APL 
for VSPC: Terminal User's Guide. 

HDR LABEL I/O ERROR. CONVERSION CANCELLED 

Explanation: An unrecoverable error occurred while an input header label 
was being read. 

System Action: Execution of the conversion program is terminated. 

User Action: Obtain another copy of the input tape from the source APL 
system. 

Issued by: APLCVCMS, APLCVOS, APLCVDOS. 

TRLR LABEL I/O ERROR. CONVERSION CANCELLED 

Explanation: An unrecoverable error occurred while an input trailer label was 
being read. 

System Action: Execution of the conversion program is terminated. 

User Action: If the error occurred on the last or only volume, none. 
Otherwise, run the conversion program again using the remaining volumes. 

Issued by: APLCVCMS, APLCVOS, APLCVDOS. 

SYSTEM ERROR WHILE CONVERTING WORKSPACE/DIRECTORY 
libnum name. WORKSPACE/DIRECTORY UNCONVERTED AND 
PRESUMED DAMAGED 

Explanation: A program check occurred, probably because of invalid 
information in a workspace or directory. 

System Action: The contents of the program check old PSW and general 
registers are printed. Execution of the conversion program continues with the 
next workspace. 

User Action: Obtain another copy of the rejected workspace or library from 
the source APL system. 

Issued by: APLCVCMS, APLCVRPQ, APLCVOS, APLCVDOS. 
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ERROR UNRECOVERABLE. CONVERSION ABORTED 

Explanation: Repeated system errors have occurred. 

System Action: A storage dump is printed. Execution of the conversion 
program is terminated. 

User Action: Obtain another copy of the input tape from the source APL 
system. 

Issued by: APLCVCMS, APLCVRPQ, APLCVOS, APLCVDOS. 

WORKSPACE REJECTED, NOT CONVERTED, DUE TO I/O ERROR 

Explanation: An unrecoverable error occurred while the workspace was being 
read. 

System Action: Execution of the conversion program continues with the next 
workspace. 

User Action: Obtain another copy of the rejected workspace from the source 
APL system. 

Issued by: APLCVCMS, APLCVRPQ, APLCVOS, APLCVDOS. 

WORKSPACE FULL 

Explanation: The workspace is too large to be converted. 

System Action: Execution of the conversion program continues with the next 
object in the workspace. 

User Action: Have the owner of the source workspace compress it or split it 
into two workspaces and obtain a dump of the modified workspace. 

Issued by: APLCVCMS, APLCVOS, APLCVDOS. 

WRITE ERROR nn WHILE SAVING libnum name. CONVERSION 
CANCELLED 

Explanation: An error return from the FSWRITE macro occurred, nn is the 
return code (see IBM Virtual Machine Facility/ 3 70: Command Language 
Guide for General Users. ) The probable cause of the error is a full A-disk 
(return code 13). 

System Action: Execution of the conversion program is terminated. 

User Action: Determine the reason for the error and correct it. Then run the 
conversion program again, specifying the RESUME option and the 
identification of the rejected workspace. 

Issued by: APLCVCMS. 

filename filetype IMPORT FILE SEQUENCE NUMBER nnnn 

Explanation: Display of the file sequence number nnnn of the converted 
workspace filename filetype on the output tape. 

System Action: None. 

User Action: Use the information when preparing VSPC Service Program 
control statements. 

Issued by: APLCVRPQ. 
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NOT A CMS DUMP TAPE. CONVERSION CANCELLED 

Explanation: The input tape is not a CMS dump tape. 

System Action: Execution of the conversion program is terminated. 

User Action: Mount the correct tape. 

Issued by: APLCVRPQ. 

filename filetype filemode NOT AN APL/CMS (PRPQ) WORKSPACE. 

Explanation: The file is not an APL/CMS workspace. 

System Action: Execution of the conversion program continues with the next 
file. 

User Action: None, unless all files on the tape are so rejected. In this case, 
mount the correct tape. 

Issued by: APLCVRPQ. 

INADEQUATE SPACE TO RUN CONVERSION. CONVERSION 
CANCELLED 

Explanation: There is less than 64K of free virtual storage space available. 

System Action: Execution of the conversion program is terminated. 

User Action: Define a larger virtual machine. 

Issued by: APLCVRPQ. 

filename filetype WORKSPACE TOO LARGE FOR VIRTUAL MACHINE 
SIZE. RERUN WITH LARGER MACHINE. WSSIZE IS xxxx NEED 
ABOUT yyyy BYTES TO CONVERT. 

Explanation: The workspace is too large to be converted. 

System Action: Execution of the conversion program continues with the next 
workspace. 

User Action: Define a larger virtual machine and run the conversion program 
again. 

Issued by: APLCVRPQ. 

filename filetype WORKSPACE DAMAGED OR INVALID. NOT 
CONVERTED. 

Explanation: Either internal pointers in the workspace are invalid, or the 
workspace is not Version 2. 

System Action: Execution of the conversion program continues with the next 
workspace. 

User Action: Obtain a valid copy of the rejected workspace from the source 
APL system. 

Issued by: APLCVRPQ. 
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WSID INVALID FOR VSPC. WORKSPACE (OR LIBRARY) REJECTED 

Explanation: The workspace name contains deltas or underscored characters 
or the library number exceeds seven digits. 

System Action: Execution of the conversion program continues with the next 
workspace. 

User Action: Run the conversion program again, using a SELECT statement 
to provide a valid identification for the rejected workspace or library. 

Issued by: APLCVOS, APLCVDOS. 

* THIS LIBRARY DEFINED WITH DEFAULTS DUE TO SYSTEM 
ERROR 

Explanation: An error occurred while the directory for the library was being 
read. 

System Action: A user profile record containing default values for SPACE 
and SSMAX is written (see "User Profiles Created by Conversion Program"). 
Execution of the conversion program continues. 

User Action: If defaults are acceptable, none. Otherwise, use the VSPC 
command ALTER to modify the user's profile. 

Issued by: APLCVOS, APLCVDOS. 

SELECTION LIST FULL. COMMAND IGNORED 

Explanation: More than 100 SELECT statements were input to the 
conversion program. 

System Action: The SELECT statements in excess of 100 are ignored. 

User Action: Run the conversion program with the rejected SELECT 
statements. 

Issued by: APLCVOS, APLCVDOS. 

INVALID SELECT PARAMETER. COMMAND IGNORED 

Explanation: The SELECT statement contains an invalid parameter. 

System Action: The invalid statement is ignored. 

User Action: Correct the SELECT statement and run the conversion 
program again. 

Issued by: APLCVOS, APLCVDOS. 

INVALID DESCRIBE COMMAND. CONVERSION CANCELLED 

Explanation: The DESCRIBE statement contains an invalid parameter. 

System Action: Execution of the conversion program is terminated. 

User Action: Correct the DESCRIBE statement and run the conversion 
program again. 

Issued by: APLCVOS, APLCVDOS. 
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INVALID CONVERSION OPTIONS. CONVERSION CANCELLED 

Explanation: Either the RESUME statement contains an invalid parameter or 
a conversion control statement is unrecognizable. 

System Action: Execution of the conversion program is terminated. 

User Action: Correct the invalid statement and run the conversion program 
again. 

Issued by: APLCVOS, APLCVDOS. 
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APPENDIX A. VS APL COMPONENTS 



Listed below are the items that 
are contained in each component 
of VS APL. When you install VS 
APL, check the printed output of 
the installation procedure against 
these lists to verify that each 
component is complete. 

Interpreter Modules 

APLCOIBM 

APLIACHK 

APLIACIR 

APLIADEC 

APLIADOM 

APLIAENC 

APLIAFOR 

APLIAGFM 

APLIAGOU 

APLIAGRD 

APLIANAM 

APLIAPRD 

APLIAQFN 

APLIARED 

APLIAROT 

APLIASCN 

APLIASHF 

APLIASHV 

APLIASYV 

APLIATAK 

APLIATBC 

APLIATRN 

APLIATRS 

APLIATSP 

APLIECMX 

APLIEFCH 

APLIEFNM 

APLIEIDX 

APLIEMND 

APLIEPSI 

APLIEREV 

APLIERHO 

APLIESCA 

APLIESPA 

APLIETAK 

APLIEXAR 

APLIEXFR 

APLITCMC 

APLITCMD 

APLITCME 

APLITCMF 

APLITCMG 

APLITCMI 



APLITCML 

APLITCMS 

APLITCMT 

APLITCPI 

APLITCPO 

APLITERR 

APLITEX 

APLITFCH 

APLITFDC 

APLITFDE 

APLITFDN 

APLITFDO 

APLITFUN 

APLITHDR 

APLITIDS 

APL1TIHI 

APLITINI 

APLITINP 

APLITLXS 

APLITMSG 

APLITNCV 

APLITPRL 

APLITSUB 

APLITUSG 

CMS Executor Modules 

APLSCDPY 

APLSCERR 

APLSCFXI 

APLSCINI 

APLSCLIB 

APLSCMSC 

APLSCMSG 

APLSCOPY 

APLSCSHV 

APLSCSVI 

APLSCTBL 

APLSCTYP 

VSPC Executor Modules 

APLPAPAB 

APLPAPCD 

APLPCOAP 

APLPCOEX 

APLPCTBL 

APLPFXIM 

APLPLIBS 

APLPMISC 

APLPSERR 

APLPSHVR 

APLPTYIO 



Shared Storage Manager Modules 
(CMS only) 

ASUSHACC 

ASUSHBPB 

ASUSHBVB 

ASUSHCPY 

ASUSHGET 

ASUSHOFR 

ASUSHPUT 

ASUSHQUE 

ASUSHREF 

ASUSHRET 

ASUSHSOF 

ASUSHSON 

ASUSHSPC 

ASUSHSRD 

ASUSHSUB 

Auxiliary Processors (CMS only) 

APL 100 
APL101 
APL110 
APL111 
APL123 

Auxiliary Processor Macros 
(CMS only) 

APLZCODE 

ASUPCV 

ASUSCV 

ASUSHSVP 

ASVPACC 

ASVPCPY 

ASVPOFR 

ASVPQRY 

ASVPREF 

ASVPRET 

ASVPSOF 

ASVPSON 

ASVPSPC 

ASVPWAIT 

CMS Conversion Modules (for 
APLCVCMS) 

APLCCULL 

APLCDISP 

APLCFUNC 

APLCGRUP 

APLCIBNM 

APLCINIT 
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APLCLEAR 

APLCMISC 

APLCOIBM 

APLCPARM 

APLCRPRT 

APLCSAVE 

APLCSHIP 

APLCSPIE 

APLCTBCD 

APLCVARB 

APLCWKSP 

APLCWSFN 

APLIESPA 

APLIEREV 

APLITFDC 

APLITHDR 

APLITIDS 

APLITLXS 

APLITNCV 



APLODIRE 

APLODISP 

APLOFUNC 

APLOGRUP 

APLOIBNM 

APLOINIT 

APLOLEAR 

APLOMISC 

APLOPARM 

APLORPRT 

APLOSAVE 

APLOSHIP 

APLOSLST 

APLOSPIE 

APLOTBCD 

APLOTIDY 

APLOVARB 

APLOWKSP 

APLOWSFN 



CMS Conversion Modules (for 
APLCVRPQ) 

APLCOIBM 

APLCSHIP 

APLCTBCD 

APLIESPA 

APLITFDC 

APLITHDR 

APLITIDS 

APLITLXS 

APLITNCV 

APLQDISP 

APLQFUNC 

APLQGRUP 

APLQIBNM 

APLQINIT 

APLQLEAR 

APLQMISC 

APLQPARM 

APLQRPRT 

APLQSAVE 

APLQSPIE 

APLQVARB 

APLQWKSP 

VSPC/OS Conversion Modules 

APLCOIBM 

APLIEREV 

APLIESPA 

APLITFDC 

APLITHDR 

APLITIDS 

APLITLXS 

APLITNCV 

APLOCULL 



VSPC/DOS Conversion Modules 

APLCOIBM 

APLDCULL 

APLDDIRE 

APLDDISP 

APLDFUNC 

APLDGRUP 

APLDIBNM 

APLDINIT 

APLDLEAR 

APLDMISC 

APLDPARM 

APLDRPRT 

APLDSAVE 

APLDSHIP 

APLDSLST 

APLDSPIE 

APLDTBCD 

APLDTIDY 

APLDVARB 

APLDWKSP 

APLDWSFN 

APLIEREV 

APLIESPA 

APLITFDC 

APLITHDR 

APLITIDS 

APLITLXS 

APLITNCV 
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APPENDIX B. SAMPLE TERMINAL SESSION FOR 
VS APL UNDER CMS 



Log on to VM/370, IPL CMS, and execute the VS APL session shown 
below. You must have access to the disk on which the VS APL system resides 
and to the Y-disk on which the distributed workspaces reside. 



APL APL100 



Invoke VS APL and the 
auxiliary processor that 
issues CP and CMS commands 



V S APL 



CLEAR WS 








IOC 


) QSVO 'X' 




Establish connection with 


2 


L * J/0000001 y 


auxiliary processor 

Issue CMS command to list 


NEWS 
TYPEDHIL 


J/0000001 
J/0000001 


Yl 


workspaces in public library 1 


APL C OURS 


J/0000001 


Yl 




CONVERT 


J/0000001 


Yl 




EXAMPLES 


J/0000001 


Yl 




PLOT 


J/0000001 


Yl 




FORMAT 


J/0000001 


Yl 




WSFNS 


J/0000001 


Yl 




SEDIT 


J/0000001 


Yl 




MEDIT 


J/0000001 


Yl 




HOWEDITS 


J/0000001 


Yl 




SBIC 


J/0000001 


Yl 




)LOAD 1 EXAMPLES 
SAVED 08:50:42 06/12/75 


Load workspace 


FINDTYPE » 7 » 
1 




Data type of argument is . . . 
character 


FINDTYPE 7 




Data type of argument is . . . 



)0FF HOLD 



PC 



numeric 

Log off VS APL and return 

to CMS 
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APPENDIX C. SAMPLE TERMINAL SESSION FOR 
VS APL UNDER VSPC 



Log on to VSPC and execute the VS APL session shown below. If the user 
number that you log on with has a content attribute of APL, omit the first 
statement. 



ENTER APL 



V S APL 



CLEAR 


WS 






)L0AD 2 1 


VSFILES 


SAVED 


11:05: 17 


07/29/75 




'S' AC RE ATE 'SAMPLE 1 




AWRITE 3 


4pil2 




AW RITE 4 


3pil2 




ARE AD 




1 2 


3 4 




5 6 


7 8 




9 10 


11 12 
ARE AD 




1 2 


3 




4 5 


6 




7 8 


9 




10 11 


12 
ARE AD 






DROP 'SAMPLE' 




)0FF HOLD 



Invoke VS APL 



Load workspace 

Create VSPC APL file to 
be accessed sequentially 
Open file and write record 1 
Write record 2 
Read record 1 



Read record 2 



p €aL + 



There is no record 3; 

file is closed 

Purge the file 

Log off VS APL and return 

to VSPC 
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GLOSSARY 



The following terms are defined as they are used in this 
publication. If you do not find the term you are looking for, 
refer to the index or to the IBM Data Processing Glossary, 
GC20-1699. 

A-disk: In CMS, a user's primary disk; accessed in read/write 
mode when a CMS terminal session is begun. 

account administrator: A VSPC user who has limited authority 
to use the VSPC Service Program and to define and alter user 
profiles. 

auxiliary processor: A program that communicates with other 
programs via shared variables. 

chief administrator: A VSPC user who has full authority to use 
the VSPC Service Program and to define and alter user, 
foreground processor, and auxiliary processor profiles. 

content attribute: In VSPC, information associated with a 
workspace that identifies its foreground processor or 
indicates its contents. 

content conversion: A form of workspace conversion in which 
the contents of a workspace are analyzed and modified; 
includes format conversion. 

conversion program: The component of VS APL that converts 
APL\360, APLSV, and APL/CMS workspaces to VS APL 
workspaces. 

core image library: A DOS/VS library used to store link-edited 
programs. For DOS/VS(VSPC), the core image library is 
used to contain the APL foreground processor and the APL 
workspace conversion program. 

executor: The component of VS APL that provides 
environment-dependent services for the interpreter. 

filemode: In CMS, the third field of a file identifier; identifies 
the virtual disk on which the file resides and the mode in 
which the disk can be accessed. 

filename: In CMS, the first field of a file identifier. 

filetype: In CMS, the second field of a file identifier; may 
implicitly define certain file characteristics. 

foreground processor: A processor, such as VS APL, that 
operates under the control of VSPC. 

format conversion: A form of workspace conversion in which 
only the format of a workspace is modified. 

full conversion: A form of workspace conversion in which all 
input workspaces are converted. 

internal auxiliary processor: An auxiliary processor that is part 
of the VS APL (VSPC) executor, rather than a separate 
program. 

interpreter: The component of VS APL that scans, analyzes, 
and executes VS APL statements. 

library manager: A VSPC user whose user number is that of a 
public or project library. 

library table file: A file that defines public and project 
libraries to VS APL under CMS. 

private library: A library that is normally available only to a 
single user. 



profile: A collection of information about a user, a 
foreground processor, or an auxiliary processor. 

project library: A library that is normally available to a set of 
users. 

public library: A library that is normally available to all users. 

relocatable library: A DOS/VS library containing relocatable 
object modules. For DOS/VS(VSPC), the relocatable library 
is used to contain object decks from the VS APL distribution 
volume. 

selective conversion: A form of workspace conversion in 
which only specified input workspaces are converted. 

service program: In VSPC, a program that is used to manage 
the VSPC library and to define and alter profiles. 

shared storage manager: The component of VSPC or of VS 
APL under CMS that manages the communication between 
auxiliary processors. 

system disk: In CMS, the disk that contains the CMS nucleus 
and disk-resident command modules; accessed in read/only 
mode when a CMS terminal session is begun. 

workspace: An area of virtual storage assigned to a user for 
his exclusive use. Also, the contents of that area when stored 
as a file. 

Y-disk: In CMS, a disk that is an extension of the system disk. 
It contains VS APL modules, procedures, and public libraries. 
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A-disk,CMS 

for installing VS APL 20-22 
for VSAPL user 39 
for workspace conversion 50 
list of files 21 

space required for VS APL 70 
AUTH statement, VSPC 
for installing VS APL 

under DOS/VS (VSPC) 3 1 ,36-37 
under OS/VS (VSPC) 30,25 
for transferring converted 
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auxiliary processor macros 
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auxiliary processors 
description 13 
how to define 
to CMS 41 
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auxiliary storage requirements 69-71 
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changing workspace identifications 
after conversion 53-55 
before conversion 49 
during conversion 
under CMS 53 
under VSPC 57 
required changes 49,51,55 
components of VS APL 
description 13 
list of contents 81-82 
content conversion 
description 50 
how to specify 
for CMS 52 
for VSPC 56 
conversion (see workspace conversion) 
creating VS APL libraries 
under CMS 43-46 
under VSPC 46-47,29-30 

D 

DEFINE statement, VSPC 
for auxiliary processors 30 
for converted libraries 60-61 
for project libraries 46 
for public libraries 46,30 
for VSAPL 30 
for VSAPL user 40 



defining auxiliary processors 

to CMS 41 

to VSPC 41,30 
defining VS APL libraries 

to CMS 43-46 

to VSPC 46-47,29 
defining VS APL users 

toVM/370 39 

to VSPC 40 
DESCRIBE statement, conversion program 57-58 
directory entry, VM/370 

for project library disk 46 

for VSAPL user 39 
distributed workspaces 

auxiliary storage requirements 70 

description 13 

how to transfer to VSPC 29-30 

identification 16,17 
distribution volume, VS APL 16,17 
DOS/VS workspace conversion program 60 

E 

error messages 

conversion program 75-79 

under CMS 73 

under VSPC 73-75 
executor, VS APL 

description 13 

list of modules 81 

messages 73-75 
EXPORT statement, VSPC 64 



format conversion 
description 50 
how to specify 
for CMS 52 
for VSPC 56 
format of conversion program statements 56 
format of VS APL distribution volume 1 5 
FORMAT statement, conversion program 56 
full conversion 
description 49 
how to specify 
for CMS 52 
for VSPC 57 



G-disk,CMS 

for project libraries 45 

how to define 46 

restriction on definition 39,46 

H 

how to maintain a public library 44-45 
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IMPORT statement, VSPC 

for converted workspaces 55 

for distributed workspaces 30 

for workspaces transported from CMS 63 
installing VS APL 

under DOS/VS (VSPC) 31-38 

under OS/VS (VSPC) 25-30 

under VM/370 (CMS) 19-23 
internal auxiliary processors 

description 13 

how to define to VSPC 29-30 

identification 41 
interpreter, VS APL 

description 13 

list of modules 81 



JCL for DOS/VS 

how to punch 32 

to build core image library 34 

to build relocatable library 33 

to define private libraries 32 

to run conversion program 60 

to run VSPC Service Program 35-37 
JCL for OS/VS 

how to punch 26 

to build VS APL object module library 27 

to define OS libraries 27 

to link-edit conversion program 28 

to link-edit VS APL load module 28 

to run conversion program 59 

to run VSPC Service Program 29-30 



library (see private library, project library, public library) 

library number, restriction 49 

library space quota 58 

library table file 43 

link-edit 

conversion program 28 

VS APL load module 28 

M 

macros, auxiliary processor 

description 1 3 

list of names 81 
maintaining VS APL libraries 

under CMS 44-46 

under VSPC 47 
messages 

conversion program 75-79 

under CMS 73 

under VSPC 73-75 
microcode assist 67 

o 

OS/VS workspace conversion program 59 



passwords 

for project library disks 46 
for VSPC, restrictions 49 
private library 
under CMS 39 
under VSPC 40 
profile, VSPC user 

created by conversion program 60-61 
example 40 
project library 
under CMS 

description 45 

how to create 45-46 

how to maintain 46 
under VSPC 

how to create 47 

how to maintain 47 
public library 
under CMS 

description 44 

how to add or replace a workspace 44 

how to create 44 

how to delete a workspace 45 
under VSPC 

how to create 46 

how to maintain 47 



Q 



61 



57 



quotas, VSPC 

library space 58 

number of shared variables 

shared variable size 58 

R 

RESUME statement, conversion program 
resuming workspace conversion 

description 49 

under CMS 52-53 

under VSPC 57 



sample JCL (see JCL) 
sample terminal session 

for CMS 83 

for VSPC 85 
SELECT statement, conversion program 57 
selective conversion 

description 49 

how to specify 
for CMS 52 
for VSPC 57 
shared storage manager 

description 13 

list of modules 81 
shared system 

installing 19-23 

storage requirements 
auxiliary 69-71 
virtual 69 

virtual machine size 39 
shared variable quotas 58,61 
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storage requirements 
auxiliary storage 
forVSAPL 69-71 
for workspace conversion 50 
for workspaces 70 
virtual storage 69 
syntax conventions 4 
system disk, CMS 23 



terminal session, sample 

for CMS 83 

forVSPC 85 
transferring conversion program output to VSPC 61 
transporting workspaces 

from CMS to VSPC 63 

from VSPC to CMS 64 

u 

user profile, VSPC 

created by conversion program 60-61 

example 40 
users of VS APL 

how to define to VM/370 39 

how to define to VSPC 40 



workspace identification 
APL/CMS workspaces 51 
converted workspaces 
for CMS 51 
for VSPC 61 
how to change 

after conversion 53-54 
before conversion 49 
during conversion 
under CMS 54 
under VSPC 57 
restrictions 49 
under CMS 

private workspaces 51 
project workspaces 45 
public workspaces 44 
workspace size 

computed by conversion program 60 
how to compute 70 
minimum 69 

restrictions for VSPC 40,47 
workspaces, distributed 

auxiliary storage requirements 70 
description 13 

how to transfer to VSPC 29-30 
identification 16,17 



virtual storage requirements 69 
VM/370 directory entry 

for project library disk 46 

forVSAPL user 39 

w 

workspace conversion 
error messages 75-79 
input 

description 49 
restrictions 49 
options 49-50 
output 

general description 50 
under CMS 50,55 
under VSPC 60 
under CMS 

auxiliary storage requirements 50 
procedure 51-55 
program names 50 
under VSPC 

control statements 

description of format 56 
DESCRIBE 57-58 
FORMAT 56 
RESUME 57 
SELECT 57 
procedure 56-58 
program names 56 
sample JCL for DOS/VS 60 
sample JCL for OS/VS 59 
user profiles 60-61 
workspace conversion under CMS 50-55 
workspace conversion under VSPC 56-61 



Y-disk, CMS 

for installing VS APL 19-23 

for public libraries 44 

forVSAPL user 39 

list of files 21 

space required for VS APL 70 
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